Context.java revision 247fe74c934cb3fba85aae7e051a8044f460fb11
1/*
2 * Copyright (C) 2006 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.content;
18
19import android.content.pm.ApplicationInfo;
20import android.content.pm.PackageManager;
21import android.content.res.AssetManager;
22import android.content.res.Resources;
23import android.content.res.TypedArray;
24import android.database.DatabaseErrorHandler;
25import android.database.sqlite.SQLiteDatabase;
26import android.database.sqlite.SQLiteDatabase.CursorFactory;
27import android.graphics.Bitmap;
28import android.graphics.drawable.Drawable;
29import android.media.MediaScannerConnection.OnScanCompletedListener;
30import android.net.Uri;
31import android.os.Bundle;
32import android.os.Handler;
33import android.os.Looper;
34import android.util.AttributeSet;
35
36import java.io.File;
37import java.io.FileInputStream;
38import java.io.FileNotFoundException;
39import java.io.FileOutputStream;
40import java.io.IOException;
41import java.io.InputStream;
42
43/**
44 * Interface to global information about an application environment.  This is
45 * an abstract class whose implementation is provided by
46 * the Android system.  It
47 * allows access to application-specific resources and classes, as well as
48 * up-calls for application-level operations such as launching activities,
49 * broadcasting and receiving intents, etc.
50 */
51public abstract class Context {
52    /**
53     * File creation mode: the default mode, where the created file can only
54     * be accessed by the calling application (or all applications sharing the
55     * same user ID).
56     * @see #MODE_WORLD_READABLE
57     * @see #MODE_WORLD_WRITEABLE
58     */
59    public static final int MODE_PRIVATE = 0x0000;
60    /**
61     * File creation mode: allow all other applications to have read access
62     * to the created file.
63     * @see #MODE_PRIVATE
64     * @see #MODE_WORLD_WRITEABLE
65     */
66    public static final int MODE_WORLD_READABLE = 0x0001;
67    /**
68     * File creation mode: allow all other applications to have write access
69     * to the created file.
70     * @see #MODE_PRIVATE
71     * @see #MODE_WORLD_READABLE
72     */
73    public static final int MODE_WORLD_WRITEABLE = 0x0002;
74    /**
75     * File creation mode: for use with {@link #openFileOutput}, if the file
76     * already exists then write data to the end of the existing file
77     * instead of erasing it.
78     * @see #openFileOutput
79     */
80    public static final int MODE_APPEND = 0x8000;
81
82    /**
83     * SharedPreference loading flag: when set, the file on disk will
84     * be checked for modification even if the shared preferences
85     * instance is already loaded in this process.  This behavior is
86     * sometimes desired in cases where the application has multiple
87     * processes, all writing to the same SharedPreferences file.
88     * Generally there are better forms of communication between
89     * processes, though.
90     *
91     * <p>This was the legacy (but undocumented) behavior in and
92     * before Gingerbread (Android 2.3) and this flag is implied when
93     * targetting such releases.  For applications targetting SDK
94     * versions <em>greater than</em> Android 2.3, this flag must be
95     * explicitly set if desired.
96     *
97     * @see #getSharedPreferences
98     */
99    public static final int MODE_MULTI_PROCESS = 0x0004;
100
101    /**
102     * Flag for {@link #bindService}: automatically create the service as long
103     * as the binding exists.  Note that while this will create the service,
104     * its {@link android.app.Service#onStartCommand}
105     * method will still only be called due to an
106     * explicit call to {@link #startService}.  Even without that, though,
107     * this still provides you with access to the service object while the
108     * service is created.
109     *
110     * <p>Specifying this flag also tells the system to treat the service
111     * as being as important as your own process -- that is, when deciding
112     * which process should be killed to free memory, the service will only
113     * be considered a candidate as long as the processes of any such bindings
114     * is also a candidate to be killed.  This is to avoid situations where
115     * the service is being continually created and killed due to low memory.
116     */
117    public static final int BIND_AUTO_CREATE = 0x0001;
118
119    /**
120     * Flag for {@link #bindService}: include debugging help for mismatched
121     * calls to unbind.  When this flag is set, the callstack of the following
122     * {@link #unbindService} call is retained, to be printed if a later
123     * incorrect unbind call is made.  Note that doing this requires retaining
124     * information about the binding that was made for the lifetime of the app,
125     * resulting in a leak -- this should only be used for debugging.
126     */
127    public static final int BIND_DEBUG_UNBIND = 0x0002;
128
129    /**
130     * Flag for {@link #bindService}: don't allow this binding to raise
131     * the target service's process to the foreground scheduling priority.
132     * It will still be raised to the at least the same memory priority
133     * as the client (so that its process will not be killable in any
134     * situation where the client is not killable), but for CPU scheduling
135     * purposes it may be left in the background.  This only has an impact
136     * in the situation where the binding client is a foreground process
137     * and the target service is in a background process.
138     */
139    public static final int BIND_NOT_FOREGROUND = 0x0004;
140
141    /** Return an AssetManager instance for your application's package. */
142    public abstract AssetManager getAssets();
143
144    /** Return a Resources instance for your application's package. */
145    public abstract Resources getResources();
146
147    /** Return PackageManager instance to find global package information. */
148    public abstract PackageManager getPackageManager();
149
150    /** Return a ContentResolver instance for your application's package. */
151    public abstract ContentResolver getContentResolver();
152
153    /**
154     * Return the Looper for the main thread of the current process.  This is
155     * the thread used to dispatch calls to application components (activities,
156     * services, etc).
157     */
158    public abstract Looper getMainLooper();
159
160    /**
161     * Return the context of the single, global Application object of the
162     * current process.  This generally should only be used if you need a
163     * Context whose lifecycle is separate from the current context, that is
164     * tied to the lifetime of the process rather than the current component.
165     *
166     * <p>Consider for example how this interacts with
167     * {@link #registerReceiver(BroadcastReceiver, IntentFilter)}:
168     * <ul>
169     * <li> <p>If used from an Activity context, the receiver is being registered
170     * within that activity.  This means that you are expected to unregister
171     * before the activity is done being destroyed; in fact if you do not do
172     * so, the framework will clean up your leaked registration as it removes
173     * the activity and log an error.  Thus, if you use the Activity context
174     * to register a receiver that is static (global to the process, not
175     * associated with an Activity instance) then that registration will be
176     * removed on you at whatever point the activity you used is destroyed.
177     * <li> <p>If used from the Context returned here, the receiver is being
178     * registered with the global state associated with your application.  Thus
179     * it will never be unregistered for you.  This is necessary if the receiver
180     * is associated with static data, not a particular component.  However
181     * using the ApplicationContext elsewhere can easily lead to serious leaks
182     * if you forget to unregister, unbind, etc.
183     * </ul>
184     */
185    public abstract Context getApplicationContext();
186
187    /**
188     * Return a localized, styled CharSequence from the application's package's
189     * default string table.
190     *
191     * @param resId Resource id for the CharSequence text
192     */
193    public final CharSequence getText(int resId) {
194        return getResources().getText(resId);
195    }
196
197    /**
198     * Return a localized string from the application's package's
199     * default string table.
200     *
201     * @param resId Resource id for the string
202     */
203    public final String getString(int resId) {
204        return getResources().getString(resId);
205    }
206
207    /**
208     * Return a localized formatted string from the application's package's
209     * default string table, substituting the format arguments as defined in
210     * {@link java.util.Formatter} and {@link java.lang.String#format}.
211     *
212     * @param resId Resource id for the format string
213     * @param formatArgs The format arguments that will be used for substitution.
214     */
215
216    public final String getString(int resId, Object... formatArgs) {
217        return getResources().getString(resId, formatArgs);
218    }
219
220     /**
221     * Set the base theme for this context.  Note that this should be called
222     * before any views are instantiated in the Context (for example before
223     * calling {@link android.app.Activity#setContentView} or
224     * {@link android.view.LayoutInflater#inflate}).
225     *
226     * @param resid The style resource describing the theme.
227     */
228    public abstract void setTheme(int resid);
229
230    /** @hide Needed for some internal implementation...  not public because
231     * you can't assume this actually means anything. */
232    public int getThemeResId() {
233        return 0;
234    }
235
236    /**
237     * Return the Theme object associated with this Context.
238     */
239    public abstract Resources.Theme getTheme();
240
241    /**
242     * Retrieve styled attribute information in this Context's theme.  See
243     * {@link Resources.Theme#obtainStyledAttributes(int[])}
244     * for more information.
245     *
246     * @see Resources.Theme#obtainStyledAttributes(int[])
247     */
248    public final TypedArray obtainStyledAttributes(
249            int[] attrs) {
250        return getTheme().obtainStyledAttributes(attrs);
251    }
252
253    /**
254     * Retrieve styled attribute information in this Context's theme.  See
255     * {@link Resources.Theme#obtainStyledAttributes(int, int[])}
256     * for more information.
257     *
258     * @see Resources.Theme#obtainStyledAttributes(int, int[])
259     */
260    public final TypedArray obtainStyledAttributes(
261            int resid, int[] attrs) throws Resources.NotFoundException {
262        return getTheme().obtainStyledAttributes(resid, attrs);
263    }
264
265    /**
266     * Retrieve styled attribute information in this Context's theme.  See
267     * {@link Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int)}
268     * for more information.
269     *
270     * @see Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int)
271     */
272    public final TypedArray obtainStyledAttributes(
273            AttributeSet set, int[] attrs) {
274        return getTheme().obtainStyledAttributes(set, attrs, 0, 0);
275    }
276
277    /**
278     * Retrieve styled attribute information in this Context's theme.  See
279     * {@link Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int)}
280     * for more information.
281     *
282     * @see Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int)
283     */
284    public final TypedArray obtainStyledAttributes(
285            AttributeSet set, int[] attrs, int defStyleAttr, int defStyleRes) {
286        return getTheme().obtainStyledAttributes(
287            set, attrs, defStyleAttr, defStyleRes);
288    }
289
290    /**
291     * Return a class loader you can use to retrieve classes in this package.
292     */
293    public abstract ClassLoader getClassLoader();
294
295    /** Return the name of this application's package. */
296    public abstract String getPackageName();
297
298    /** Return the full application info for this context's package. */
299    public abstract ApplicationInfo getApplicationInfo();
300
301    /**
302     * Return the full path to this context's primary Android package.
303     * The Android package is a ZIP file which contains the application's
304     * primary resources.
305     *
306     * <p>Note: this is not generally useful for applications, since they should
307     * not be directly accessing the file system.
308     *
309     * @return String Path to the resources.
310     */
311    public abstract String getPackageResourcePath();
312
313    /**
314     * Return the full path to this context's primary Android package.
315     * The Android package is a ZIP file which contains application's
316     * primary code and assets.
317     *
318     * <p>Note: this is not generally useful for applications, since they should
319     * not be directly accessing the file system.
320     *
321     * @return String Path to the code and assets.
322     */
323    public abstract String getPackageCodePath();
324
325    /**
326     * {@hide}
327     * Return the full path to the shared prefs file for the given prefs group name.
328     *
329     * <p>Note: this is not generally useful for applications, since they should
330     * not be directly accessing the file system.
331     */
332    public abstract File getSharedPrefsFile(String name);
333
334    /**
335     * Retrieve and hold the contents of the preferences file 'name', returning
336     * a SharedPreferences through which you can retrieve and modify its
337     * values.  Only one instance of the SharedPreferences object is returned
338     * to any callers for the same name, meaning they will see each other's
339     * edits as soon as they are made.
340     *
341     * @param name Desired preferences file. If a preferences file by this name
342     * does not exist, it will be created when you retrieve an
343     * editor (SharedPreferences.edit()) and then commit changes (Editor.commit()).
344     * @param mode Operating mode.  Use 0 or {@link #MODE_PRIVATE} for the
345     * default operation, {@link #MODE_WORLD_READABLE}
346     * and {@link #MODE_WORLD_WRITEABLE} to control permissions.  The bit
347     * {@link #MODE_MULTI_PROCESS} can also be used if multiple processes
348     * are mutating the same SharedPreferences file.  {@link #MODE_MULTI_PROCESS}
349     * is always on in apps targetting Gingerbread (Android 2.3) and below, and
350     * off by default in later versions.
351     *
352     * @return Returns the single SharedPreferences instance that can be used
353     *         to retrieve and modify the preference values.
354     *
355     * @see #MODE_PRIVATE
356     * @see #MODE_WORLD_READABLE
357     * @see #MODE_WORLD_WRITEABLE
358     * @see #MODE_MULTI_PROCESS
359     */
360    public abstract SharedPreferences getSharedPreferences(String name,
361            int mode);
362
363    /**
364     * Open a private file associated with this Context's application package
365     * for reading.
366     *
367     * @param name The name of the file to open; can not contain path
368     *             separators.
369     *
370     * @return FileInputStream Resulting input stream.
371     *
372     * @see #openFileOutput
373     * @see #fileList
374     * @see #deleteFile
375     * @see java.io.FileInputStream#FileInputStream(String)
376     */
377    public abstract FileInputStream openFileInput(String name)
378        throws FileNotFoundException;
379
380    /**
381     * Open a private file associated with this Context's application package
382     * for writing.  Creates the file if it doesn't already exist.
383     *
384     * @param name The name of the file to open; can not contain path
385     *             separators.
386     * @param mode Operating mode.  Use 0 or {@link #MODE_PRIVATE} for the
387     * default operation, {@link #MODE_APPEND} to append to an existing file,
388     * {@link #MODE_WORLD_READABLE} and {@link #MODE_WORLD_WRITEABLE} to control
389     * permissions.
390     *
391     * @return FileOutputStream Resulting output stream.
392     *
393     * @see #MODE_APPEND
394     * @see #MODE_PRIVATE
395     * @see #MODE_WORLD_READABLE
396     * @see #MODE_WORLD_WRITEABLE
397     * @see #openFileInput
398     * @see #fileList
399     * @see #deleteFile
400     * @see java.io.FileOutputStream#FileOutputStream(String)
401     */
402    public abstract FileOutputStream openFileOutput(String name, int mode)
403        throws FileNotFoundException;
404
405    /**
406     * Delete the given private file associated with this Context's
407     * application package.
408     *
409     * @param name The name of the file to delete; can not contain path
410     *             separators.
411     *
412     * @return True if the file was successfully deleted; else
413     *         false.
414     *
415     * @see #openFileInput
416     * @see #openFileOutput
417     * @see #fileList
418     * @see java.io.File#delete()
419     */
420    public abstract boolean deleteFile(String name);
421
422    /**
423     * Returns the absolute path on the filesystem where a file created with
424     * {@link #openFileOutput} is stored.
425     *
426     * @param name The name of the file for which you would like to get
427     *          its path.
428     *
429     * @return Returns an absolute path to the given file.
430     *
431     * @see #openFileOutput
432     * @see #getFilesDir
433     * @see #getDir
434     */
435    public abstract File getFileStreamPath(String name);
436
437    /**
438     * Returns the absolute path to the directory on the filesystem where
439     * files created with {@link #openFileOutput} are stored.
440     *
441     * @return Returns the path of the directory holding application files.
442     *
443     * @see #openFileOutput
444     * @see #getFileStreamPath
445     * @see #getDir
446     */
447    public abstract File getFilesDir();
448
449    /**
450     * Returns the absolute path to the directory on the external filesystem
451     * (that is somewhere on {@link android.os.Environment#getExternalStorageDirectory()
452     * Environment.getExternalStorageDirectory()}) where the application can
453     * place persistent files it owns.  These files are private to the
454     * applications, and not typically visible to the user as media.
455     *
456     * <p>This is like {@link #getFilesDir()} in that these
457     * files will be deleted when the application is uninstalled, however there
458     * are some important differences:
459     *
460     * <ul>
461     * <li>External files are not always available: they will disappear if the
462     * user mounts the external storage on a computer or removes it.  See the
463     * APIs on {@link android.os.Environment} for information in the storage state.
464     * <li>There is no security enforced with these files.  All applications
465     * can read and write files placed here.
466     * </ul>
467     *
468     * <p>Here is an example of typical code to manipulate a file in
469     * an application's private storage:</p>
470     *
471     * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
472     * private_file}
473     *
474     * <p>If you supply a non-null <var>type</var> to this function, the returned
475     * file will be a path to a sub-directory of the given type.  Though these files
476     * are not automatically scanned by the media scanner, you can explicitly
477     * add them to the media database with
478     * {@link android.media.MediaScannerConnection#scanFile(Context, String[], String[],
479     *      OnScanCompletedListener) MediaScannerConnection.scanFile}.
480     * Note that this is not the same as
481     * {@link android.os.Environment#getExternalStoragePublicDirectory
482     * Environment.getExternalStoragePublicDirectory()}, which provides
483     * directories of media shared by all applications.  The
484     * directories returned here are
485     * owned by the application, and their contents will be removed when the
486     * application is uninstalled.  Unlike
487     * {@link android.os.Environment#getExternalStoragePublicDirectory
488     * Environment.getExternalStoragePublicDirectory()}, the directory
489     * returned here will be automatically created for you.
490     *
491     * <p>Here is an example of typical code to manipulate a picture in
492     * an application's private storage and add it to the media database:</p>
493     *
494     * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
495     * private_picture}
496     *
497     * @param type The type of files directory to return.  May be null for
498     * the root of the files directory or one of
499     * the following Environment constants for a subdirectory:
500     * {@link android.os.Environment#DIRECTORY_MUSIC},
501     * {@link android.os.Environment#DIRECTORY_PODCASTS},
502     * {@link android.os.Environment#DIRECTORY_RINGTONES},
503     * {@link android.os.Environment#DIRECTORY_ALARMS},
504     * {@link android.os.Environment#DIRECTORY_NOTIFICATIONS},
505     * {@link android.os.Environment#DIRECTORY_PICTURES}, or
506     * {@link android.os.Environment#DIRECTORY_MOVIES}.
507     *
508     * @return Returns the path of the directory holding application files
509     * on external storage.  Returns null if external storage is not currently
510     * mounted so it could not ensure the path exists; you will need to call
511     * this method again when it is available.
512     *
513     * @see #getFilesDir
514     * @see android.os.Environment#getExternalStoragePublicDirectory
515     */
516    public abstract File getExternalFilesDir(String type);
517
518    /**
519     * Returns the absolute path to the application specific cache directory
520     * on the filesystem. These files will be ones that get deleted first when the
521     * device runs low on storage.
522     * There is no guarantee when these files will be deleted.
523     *
524     * <strong>Note: you should not <em>rely</em> on the system deleting these
525     * files for you; you should always have a reasonable maximum, such as 1 MB,
526     * for the amount of space you consume with cache files, and prune those
527     * files when exceeding that space.</strong>
528     *
529     * @return Returns the path of the directory holding application cache files.
530     *
531     * @see #openFileOutput
532     * @see #getFileStreamPath
533     * @see #getDir
534     */
535    public abstract File getCacheDir();
536
537    /**
538     * Returns the absolute path to the directory on the external filesystem
539     * (that is somewhere on {@link android.os.Environment#getExternalStorageDirectory()
540     * Environment.getExternalStorageDirectory()} where the application can
541     * place cache files it owns.
542     *
543     * <p>This is like {@link #getCacheDir()} in that these
544     * files will be deleted when the application is uninstalled, however there
545     * are some important differences:
546     *
547     * <ul>
548     * <li>The platform does not monitor the space available in external storage,
549     * and thus will not automatically delete these files.  Note that you should
550     * be managing the maximum space you will use for these anyway, just like
551     * with {@link #getCacheDir()}.
552     * <li>External files are not always available: they will disappear if the
553     * user mounts the external storage on a computer or removes it.  See the
554     * APIs on {@link android.os.Environment} for information in the storage state.
555     * <li>There is no security enforced with these files.  All applications
556     * can read and write files placed here.
557     * </ul>
558     *
559     * @return Returns the path of the directory holding application cache files
560     * on external storage.  Returns null if external storage is not currently
561     * mounted so it could not ensure the path exists; you will need to call
562     * this method again when it is available.
563     *
564     * @see #getCacheDir
565     */
566    public abstract File getExternalCacheDir();
567
568    /**
569     * Returns an array of strings naming the private files associated with
570     * this Context's application package.
571     *
572     * @return Array of strings naming the private files.
573     *
574     * @see #openFileInput
575     * @see #openFileOutput
576     * @see #deleteFile
577     */
578    public abstract String[] fileList();
579
580    /**
581     * Retrieve, creating if needed, a new directory in which the application
582     * can place its own custom data files.  You can use the returned File
583     * object to create and access files in this directory.  Note that files
584     * created through a File object will only be accessible by your own
585     * application; you can only set the mode of the entire directory, not
586     * of individual files.
587     *
588     * @param name Name of the directory to retrieve.  This is a directory
589     * that is created as part of your application data.
590     * @param mode Operating mode.  Use 0 or {@link #MODE_PRIVATE} for the
591     * default operation, {@link #MODE_WORLD_READABLE} and
592     * {@link #MODE_WORLD_WRITEABLE} to control permissions.
593     *
594     * @return Returns a File object for the requested directory.  The directory
595     * will have been created if it does not already exist.
596     *
597     * @see #openFileOutput(String, int)
598     */
599    public abstract File getDir(String name, int mode);
600
601    /**
602     * Open a new private SQLiteDatabase associated with this Context's
603     * application package.  Create the database file if it doesn't exist.
604     *
605     * @param name The name (unique in the application package) of the database.
606     * @param mode Operating mode.  Use 0 or {@link #MODE_PRIVATE} for the
607     *     default operation, {@link #MODE_WORLD_READABLE}
608     *     and {@link #MODE_WORLD_WRITEABLE} to control permissions.
609     * @param factory An optional factory class that is called to instantiate a
610     *     cursor when query is called.
611     *
612     * @return The contents of a newly created database with the given name.
613     * @throws android.database.sqlite.SQLiteException if the database file could not be opened.
614     *
615     * @see #MODE_PRIVATE
616     * @see #MODE_WORLD_READABLE
617     * @see #MODE_WORLD_WRITEABLE
618     * @see #deleteDatabase
619     */
620    public abstract SQLiteDatabase openOrCreateDatabase(String name,
621            int mode, CursorFactory factory);
622
623    /**
624     * Open a new private SQLiteDatabase associated with this Context's
625     * application package.  Creates the database file if it doesn't exist.
626     *
627     * <p>Accepts input param: a concrete instance of {@link DatabaseErrorHandler} to be
628     * used to handle corruption when sqlite reports database corruption.</p>
629     *
630     * @param name The name (unique in the application package) of the database.
631     * @param mode Operating mode.  Use 0 or {@link #MODE_PRIVATE} for the
632     *     default operation, {@link #MODE_WORLD_READABLE}
633     *     and {@link #MODE_WORLD_WRITEABLE} to control permissions.
634     * @param factory An optional factory class that is called to instantiate a
635     *     cursor when query is called.
636     * @param errorHandler the {@link DatabaseErrorHandler} to be used when sqlite reports database
637     * corruption. if null, {@link android.database.DefaultDatabaseErrorHandler} is assumed.
638     * @return The contents of a newly created database with the given name.
639     * @throws android.database.sqlite.SQLiteException if the database file could not be opened.
640     *
641     * @see #MODE_PRIVATE
642     * @see #MODE_WORLD_READABLE
643     * @see #MODE_WORLD_WRITEABLE
644     * @see #deleteDatabase
645     */
646    public abstract SQLiteDatabase openOrCreateDatabase(String name,
647            int mode, CursorFactory factory, DatabaseErrorHandler errorHandler);
648
649    /**
650     * Delete an existing private SQLiteDatabase associated with this Context's
651     * application package.
652     *
653     * @param name The name (unique in the application package) of the
654     *             database.
655     *
656     * @return True if the database was successfully deleted; else false.
657     *
658     * @see #openOrCreateDatabase
659     */
660    public abstract boolean deleteDatabase(String name);
661
662    /**
663     * Returns the absolute path on the filesystem where a database created with
664     * {@link #openOrCreateDatabase} is stored.
665     *
666     * @param name The name of the database for which you would like to get
667     *          its path.
668     *
669     * @return Returns an absolute path to the given database.
670     *
671     * @see #openOrCreateDatabase
672     */
673    public abstract File getDatabasePath(String name);
674
675    /**
676     * Returns an array of strings naming the private databases associated with
677     * this Context's application package.
678     *
679     * @return Array of strings naming the private databases.
680     *
681     * @see #openOrCreateDatabase
682     * @see #deleteDatabase
683     */
684    public abstract String[] databaseList();
685
686    /**
687     * @deprecated Use {@link android.app.WallpaperManager#getDrawable
688     * WallpaperManager.get()} instead.
689     */
690    @Deprecated
691    public abstract Drawable getWallpaper();
692
693    /**
694     * @deprecated Use {@link android.app.WallpaperManager#peekDrawable
695     * WallpaperManager.peek()} instead.
696     */
697    @Deprecated
698    public abstract Drawable peekWallpaper();
699
700    /**
701     * @deprecated Use {@link android.app.WallpaperManager#getDesiredMinimumWidth()
702     * WallpaperManager.getDesiredMinimumWidth()} instead.
703     */
704    @Deprecated
705    public abstract int getWallpaperDesiredMinimumWidth();
706
707    /**
708     * @deprecated Use {@link android.app.WallpaperManager#getDesiredMinimumHeight()
709     * WallpaperManager.getDesiredMinimumHeight()} instead.
710     */
711    @Deprecated
712    public abstract int getWallpaperDesiredMinimumHeight();
713
714    /**
715     * @deprecated Use {@link android.app.WallpaperManager#setBitmap(Bitmap)
716     * WallpaperManager.set()} instead.
717     */
718    @Deprecated
719    public abstract void setWallpaper(Bitmap bitmap) throws IOException;
720
721    /**
722     * @deprecated Use {@link android.app.WallpaperManager#setStream(InputStream)
723     * WallpaperManager.set()} instead.
724     */
725    @Deprecated
726    public abstract void setWallpaper(InputStream data) throws IOException;
727
728    /**
729     * @deprecated Use {@link android.app.WallpaperManager#clear
730     * WallpaperManager.clear()} instead.
731     */
732    @Deprecated
733    public abstract void clearWallpaper() throws IOException;
734
735    /**
736     * Launch a new activity.  You will not receive any information about when
737     * the activity exits.
738     *
739     * <p>Note that if this method is being called from outside of an
740     * {@link android.app.Activity} Context, then the Intent must include
741     * the {@link Intent#FLAG_ACTIVITY_NEW_TASK} launch flag.  This is because,
742     * without being started from an existing Activity, there is no existing
743     * task in which to place the new activity and thus it needs to be placed
744     * in its own separate task.
745     *
746     * <p>This method throws {@link ActivityNotFoundException}
747     * if there was no Activity found to run the given Intent.
748     *
749     * @param intent The description of the activity to start.
750     *
751     * @throws ActivityNotFoundException
752     *
753     * @see PackageManager#resolveActivity
754     */
755    public abstract void startActivity(Intent intent);
756
757    /**
758     * Launch multiple new activities.  This is generally the same as calling
759     * {@link #startActivity(Intent)} for the first Intent in the array,
760     * that activity during its creation calling {@link #startActivity(Intent)}
761     * for the second entry, etc.  Note that unlike that approach, generally
762     * none of the activities except the last in the array will be created
763     * at this point, but rather will be created when the user first visits
764     * them (due to pressing back from the activity on top).
765     *
766     * <p>This method throws {@link ActivityNotFoundException}
767     * if there was no Activity found for <em>any</em> given Intent.  In this
768     * case the state of the activity stack is undefined (some Intents in the
769     * list may be on it, some not), so you probably want to avoid such situations.
770     *
771     * @param intents An array of Intents to be started.
772     *
773     * @throws ActivityNotFoundException
774     *
775     * @see PackageManager#resolveActivity
776     */
777    public abstract void startActivities(Intent[] intents);
778
779    /**
780     * Like {@link #startActivity(Intent)}, but taking a IntentSender
781     * to start.  If the IntentSender is for an activity, that activity will be started
782     * as if you had called the regular {@link #startActivity(Intent)}
783     * here; otherwise, its associated action will be executed (such as
784     * sending a broadcast) as if you had called
785     * {@link IntentSender#sendIntent IntentSender.sendIntent} on it.
786     *
787     * @param intent The IntentSender to launch.
788     * @param fillInIntent If non-null, this will be provided as the
789     * intent parameter to {@link IntentSender#sendIntent}.
790     * @param flagsMask Intent flags in the original IntentSender that you
791     * would like to change.
792     * @param flagsValues Desired values for any bits set in
793     * <var>flagsMask</var>
794     * @param extraFlags Always set to 0.
795     */
796    public abstract void startIntentSender(IntentSender intent,
797            Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags)
798            throws IntentSender.SendIntentException;
799
800    /**
801     * Broadcast the given intent to all interested BroadcastReceivers.  This
802     * call is asynchronous; it returns immediately, and you will continue
803     * executing while the receivers are run.  No results are propagated from
804     * receivers and receivers can not abort the broadcast. If you want
805     * to allow receivers to propagate results or abort the broadcast, you must
806     * send an ordered broadcast using
807     * {@link #sendOrderedBroadcast(Intent, String)}.
808     *
809     * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts.
810     *
811     * @param intent The Intent to broadcast; all receivers matching this
812     *               Intent will receive the broadcast.
813     *
814     * @see android.content.BroadcastReceiver
815     * @see #registerReceiver
816     * @see #sendBroadcast(Intent, String)
817     * @see #sendOrderedBroadcast(Intent, String)
818     * @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle)
819     */
820    public abstract void sendBroadcast(Intent intent);
821
822    /**
823     * Broadcast the given intent to all interested BroadcastReceivers, allowing
824     * an optional required permission to be enforced.  This
825     * call is asynchronous; it returns immediately, and you will continue
826     * executing while the receivers are run.  No results are propagated from
827     * receivers and receivers can not abort the broadcast. If you want
828     * to allow receivers to propagate results or abort the broadcast, you must
829     * send an ordered broadcast using
830     * {@link #sendOrderedBroadcast(Intent, String)}.
831     *
832     * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts.
833     *
834     * @param intent The Intent to broadcast; all receivers matching this
835     *               Intent will receive the broadcast.
836     * @param receiverPermission (optional) String naming a permission that
837     *               a receiver must hold in order to receive your broadcast.
838     *               If null, no permission is required.
839     *
840     * @see android.content.BroadcastReceiver
841     * @see #registerReceiver
842     * @see #sendBroadcast(Intent)
843     * @see #sendOrderedBroadcast(Intent, String)
844     * @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle)
845     */
846    public abstract void sendBroadcast(Intent intent,
847            String receiverPermission);
848
849    /**
850     * Broadcast the given intent to all interested BroadcastReceivers, delivering
851     * them one at a time to allow more preferred receivers to consume the
852     * broadcast before it is delivered to less preferred receivers.  This
853     * call is asynchronous; it returns immediately, and you will continue
854     * executing while the receivers are run.
855     *
856     * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts.
857     *
858     * @param intent The Intent to broadcast; all receivers matching this
859     *               Intent will receive the broadcast.
860     * @param receiverPermission (optional) String naming a permissions that
861     *               a receiver must hold in order to receive your broadcast.
862     *               If null, no permission is required.
863     *
864     * @see android.content.BroadcastReceiver
865     * @see #registerReceiver
866     * @see #sendBroadcast(Intent)
867     * @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle)
868     */
869    public abstract void sendOrderedBroadcast(Intent intent,
870            String receiverPermission);
871
872    /**
873     * Version of {@link #sendBroadcast(Intent)} that allows you to
874     * receive data back from the broadcast.  This is accomplished by
875     * supplying your own BroadcastReceiver when calling, which will be
876     * treated as a final receiver at the end of the broadcast -- its
877     * {@link BroadcastReceiver#onReceive} method will be called with
878     * the result values collected from the other receivers.  The broadcast will
879     * be serialized in the same way as calling
880     * {@link #sendOrderedBroadcast(Intent, String)}.
881     *
882     * <p>Like {@link #sendBroadcast(Intent)}, this method is
883     * asynchronous; it will return before
884     * resultReceiver.onReceive() is called.
885     *
886     * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts.
887     *
888     * @param intent The Intent to broadcast; all receivers matching this
889     *               Intent will receive the broadcast.
890     * @param receiverPermission String naming a permissions that
891     *               a receiver must hold in order to receive your broadcast.
892     *               If null, no permission is required.
893     * @param resultReceiver Your own BroadcastReceiver to treat as the final
894     *                       receiver of the broadcast.
895     * @param scheduler A custom Handler with which to schedule the
896     *                  resultReceiver callback; if null it will be
897     *                  scheduled in the Context's main thread.
898     * @param initialCode An initial value for the result code.  Often
899     *                    Activity.RESULT_OK.
900     * @param initialData An initial value for the result data.  Often
901     *                    null.
902     * @param initialExtras An initial value for the result extras.  Often
903     *                      null.
904     *
905     * @see #sendBroadcast(Intent)
906     * @see #sendBroadcast(Intent, String)
907     * @see #sendOrderedBroadcast(Intent, String)
908     * @see #sendStickyBroadcast(Intent)
909     * @see #sendStickyOrderedBroadcast(Intent, BroadcastReceiver, Handler, int, String, Bundle)
910     * @see android.content.BroadcastReceiver
911     * @see #registerReceiver
912     * @see android.app.Activity#RESULT_OK
913     */
914    public abstract void sendOrderedBroadcast(Intent intent,
915            String receiverPermission, BroadcastReceiver resultReceiver,
916            Handler scheduler, int initialCode, String initialData,
917            Bundle initialExtras);
918
919    /**
920     * Perform a {@link #sendBroadcast(Intent)} that is "sticky," meaning the
921     * Intent you are sending stays around after the broadcast is complete,
922     * so that others can quickly retrieve that data through the return
923     * value of {@link #registerReceiver(BroadcastReceiver, IntentFilter)}.  In
924     * all other ways, this behaves the same as
925     * {@link #sendBroadcast(Intent)}.
926     *
927     * <p>You must hold the {@link android.Manifest.permission#BROADCAST_STICKY}
928     * permission in order to use this API.  If you do not hold that
929     * permission, {@link SecurityException} will be thrown.
930     *
931     * @param intent The Intent to broadcast; all receivers matching this
932     * Intent will receive the broadcast, and the Intent will be held to
933     * be re-broadcast to future receivers.
934     *
935     * @see #sendBroadcast(Intent)
936     * @see #sendStickyOrderedBroadcast(Intent, BroadcastReceiver, Handler, int, String, Bundle)
937     */
938    public abstract void sendStickyBroadcast(Intent intent);
939
940    /**
941     * Version of {@link #sendStickyBroadcast} that allows you to
942     * receive data back from the broadcast.  This is accomplished by
943     * supplying your own BroadcastReceiver when calling, which will be
944     * treated as a final receiver at the end of the broadcast -- its
945     * {@link BroadcastReceiver#onReceive} method will be called with
946     * the result values collected from the other receivers.  The broadcast will
947     * be serialized in the same way as calling
948     * {@link #sendOrderedBroadcast(Intent, String)}.
949     *
950     * <p>Like {@link #sendBroadcast(Intent)}, this method is
951     * asynchronous; it will return before
952     * resultReceiver.onReceive() is called.  Note that the sticky data
953     * stored is only the data you initially supply to the broadcast, not
954     * the result of any changes made by the receivers.
955     *
956     * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts.
957     *
958     * @param intent The Intent to broadcast; all receivers matching this
959     *               Intent will receive the broadcast.
960     * @param resultReceiver Your own BroadcastReceiver to treat as the final
961     *                       receiver of the broadcast.
962     * @param scheduler A custom Handler with which to schedule the
963     *                  resultReceiver callback; if null it will be
964     *                  scheduled in the Context's main thread.
965     * @param initialCode An initial value for the result code.  Often
966     *                    Activity.RESULT_OK.
967     * @param initialData An initial value for the result data.  Often
968     *                    null.
969     * @param initialExtras An initial value for the result extras.  Often
970     *                      null.
971     *
972     * @see #sendBroadcast(Intent)
973     * @see #sendBroadcast(Intent, String)
974     * @see #sendOrderedBroadcast(Intent, String)
975     * @see #sendStickyBroadcast(Intent)
976     * @see android.content.BroadcastReceiver
977     * @see #registerReceiver
978     * @see android.app.Activity#RESULT_OK
979     */
980    public abstract void sendStickyOrderedBroadcast(Intent intent,
981            BroadcastReceiver resultReceiver,
982            Handler scheduler, int initialCode, String initialData,
983            Bundle initialExtras);
984
985
986    /**
987     * Remove the data previously sent with {@link #sendStickyBroadcast},
988     * so that it is as if the sticky broadcast had never happened.
989     *
990     * <p>You must hold the {@link android.Manifest.permission#BROADCAST_STICKY}
991     * permission in order to use this API.  If you do not hold that
992     * permission, {@link SecurityException} will be thrown.
993     *
994     * @param intent The Intent that was previously broadcast.
995     *
996     * @see #sendStickyBroadcast
997     */
998    public abstract void removeStickyBroadcast(Intent intent);
999
1000    /**
1001     * Register a BroadcastReceiver to be run in the main activity thread.  The
1002     * <var>receiver</var> will be called with any broadcast Intent that
1003     * matches <var>filter</var>, in the main application thread.
1004     *
1005     * <p>The system may broadcast Intents that are "sticky" -- these stay
1006     * around after the broadcast as finished, to be sent to any later
1007     * registrations. If your IntentFilter matches one of these sticky
1008     * Intents, that Intent will be returned by this function
1009     * <strong>and</strong> sent to your <var>receiver</var> as if it had just
1010     * been broadcast.
1011     *
1012     * <p>There may be multiple sticky Intents that match <var>filter</var>,
1013     * in which case each of these will be sent to <var>receiver</var>.  In
1014     * this case, only one of these can be returned directly by the function;
1015     * which of these that is returned is arbitrarily decided by the system.
1016     *
1017     * <p>If you know the Intent your are registering for is sticky, you can
1018     * supply null for your <var>receiver</var>.  In this case, no receiver is
1019     * registered -- the function simply returns the sticky Intent that
1020     * matches <var>filter</var>.  In the case of multiple matches, the same
1021     * rules as described above apply.
1022     *
1023     * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts.
1024     *
1025     * <p class="note">Note: this method <em>cannot be called from a
1026     * {@link BroadcastReceiver} component;</em> that is, from a BroadcastReceiver
1027     * that is declared in an application's manifest.  It is okay, however, to call
1028     * this method from another BroadcastReceiver that has itself been registered
1029     * at run time with {@link #registerReceiver}, since the lifetime of such a
1030     * registered BroadcastReceiver is tied to the object that registered it.</p>
1031     *
1032     * @param receiver The BroadcastReceiver to handle the broadcast.
1033     * @param filter Selects the Intent broadcasts to be received.
1034     *
1035     * @return The first sticky intent found that matches <var>filter</var>,
1036     *         or null if there are none.
1037     *
1038     * @see #registerReceiver(BroadcastReceiver, IntentFilter, String, Handler)
1039     * @see #sendBroadcast
1040     * @see #unregisterReceiver
1041     */
1042    public abstract Intent registerReceiver(BroadcastReceiver receiver,
1043                                            IntentFilter filter);
1044
1045    /**
1046     * Register to receive intent broadcasts, to run in the context of
1047     * <var>scheduler</var>.  See
1048     * {@link #registerReceiver(BroadcastReceiver, IntentFilter)} for more
1049     * information.  This allows you to enforce permissions on who can
1050     * broadcast intents to your receiver, or have the receiver run in
1051     * a different thread than the main application thread.
1052     *
1053     * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts.
1054     *
1055     * @param receiver The BroadcastReceiver to handle the broadcast.
1056     * @param filter Selects the Intent broadcasts to be received.
1057     * @param broadcastPermission String naming a permissions that a
1058     *      broadcaster must hold in order to send an Intent to you.  If null,
1059     *      no permission is required.
1060     * @param scheduler Handler identifying the thread that will receive
1061     *      the Intent.  If null, the main thread of the process will be used.
1062     *
1063     * @return The first sticky intent found that matches <var>filter</var>,
1064     *         or null if there are none.
1065     *
1066     * @see #registerReceiver(BroadcastReceiver, IntentFilter)
1067     * @see #sendBroadcast
1068     * @see #unregisterReceiver
1069     */
1070    public abstract Intent registerReceiver(BroadcastReceiver receiver,
1071                                            IntentFilter filter,
1072                                            String broadcastPermission,
1073                                            Handler scheduler);
1074
1075    /**
1076     * Unregister a previously registered BroadcastReceiver.  <em>All</em>
1077     * filters that have been registered for this BroadcastReceiver will be
1078     * removed.
1079     *
1080     * @param receiver The BroadcastReceiver to unregister.
1081     *
1082     * @see #registerReceiver
1083     */
1084    public abstract void unregisterReceiver(BroadcastReceiver receiver);
1085
1086    /**
1087     * Request that a given application service be started.  The Intent
1088     * can either contain the complete class name of a specific service
1089     * implementation to start, or an abstract definition through the
1090     * action and other fields of the kind of service to start.  If this service
1091     * is not already running, it will be instantiated and started (creating a
1092     * process for it if needed); if it is running then it remains running.
1093     *
1094     * <p>Every call to this method will result in a corresponding call to
1095     * the target service's {@link android.app.Service#onStartCommand} method,
1096     * with the <var>intent</var> given here.  This provides a convenient way
1097     * to submit jobs to a service without having to bind and call on to its
1098     * interface.
1099     *
1100     * <p>Using startService() overrides the default service lifetime that is
1101     * managed by {@link #bindService}: it requires the service to remain
1102     * running until {@link #stopService} is called, regardless of whether
1103     * any clients are connected to it.  Note that calls to startService()
1104     * are not nesting: no matter how many times you call startService(),
1105     * a single call to {@link #stopService} will stop it.
1106     *
1107     * <p>The system attempts to keep running services around as much as
1108     * possible.  The only time they should be stopped is if the current
1109     * foreground application is using so many resources that the service needs
1110     * to be killed.  If any errors happen in the service's process, it will
1111     * automatically be restarted.
1112     *
1113     * <p>This function will throw {@link SecurityException} if you do not
1114     * have permission to start the given service.
1115     *
1116     * @param service Identifies the service to be started.  The Intent may
1117     *      specify either an explicit component name to start, or a logical
1118     *      description (action, category, etc) to match an
1119     *      {@link IntentFilter} published by a service.  Additional values
1120     *      may be included in the Intent extras to supply arguments along with
1121     *      this specific start call.
1122     *
1123     * @return If the service is being started or is already running, the
1124     * {@link ComponentName} of the actual service that was started is
1125     * returned; else if the service does not exist null is returned.
1126     *
1127     * @throws SecurityException
1128     *
1129     * @see #stopService
1130     * @see #bindService
1131     */
1132    public abstract ComponentName startService(Intent service);
1133
1134    /**
1135     * Request that a given application service be stopped.  If the service is
1136     * not running, nothing happens.  Otherwise it is stopped.  Note that calls
1137     * to startService() are not counted -- this stops the service no matter
1138     * how many times it was started.
1139     *
1140     * <p>Note that if a stopped service still has {@link ServiceConnection}
1141     * objects bound to it with the {@link #BIND_AUTO_CREATE} set, it will
1142     * not be destroyed until all of these bindings are removed.  See
1143     * the {@link android.app.Service} documentation for more details on a
1144     * service's lifecycle.
1145     *
1146     * <p>This function will throw {@link SecurityException} if you do not
1147     * have permission to stop the given service.
1148     *
1149     * @param service Description of the service to be stopped.  The Intent may
1150     *      specify either an explicit component name to start, or a logical
1151     *      description (action, category, etc) to match an
1152     *      {@link IntentFilter} published by a service.
1153     *
1154     * @return If there is a service matching the given Intent that is already
1155     * running, then it is stopped and true is returned; else false is returned.
1156     *
1157     * @throws SecurityException
1158     *
1159     * @see #startService
1160     */
1161    public abstract boolean stopService(Intent service);
1162
1163    /**
1164     * Connect to an application service, creating it if needed.  This defines
1165     * a dependency between your application and the service.  The given
1166     * <var>conn</var> will receive the service object when its created and be
1167     * told if it dies and restarts.  The service will be considered required
1168     * by the system only for as long as the calling context exists.  For
1169     * example, if this Context is an Activity that is stopped, the service will
1170     * not be required to continue running until the Activity is resumed.
1171     *
1172     * <p>This function will throw {@link SecurityException} if you do not
1173     * have permission to bind to the given service.
1174     *
1175     * <p class="note">Note: this method <em>can not be called from an
1176     * {@link BroadcastReceiver} component</em>.  A pattern you can use to
1177     * communicate from an BroadcastReceiver to a Service is to call
1178     * {@link #startService} with the arguments containing the command to be
1179     * sent, with the service calling its
1180     * {@link android.app.Service#stopSelf(int)} method when done executing
1181     * that command.  See the API demo App/Service/Service Start Arguments
1182     * Controller for an illustration of this.  It is okay, however, to use
1183     * this method from an BroadcastReceiver that has been registered with
1184     * {@link #registerReceiver}, since the lifetime of this BroadcastReceiver
1185     * is tied to another object (the one that registered it).</p>
1186     *
1187     * @param service Identifies the service to connect to.  The Intent may
1188     *      specify either an explicit component name, or a logical
1189     *      description (action, category, etc) to match an
1190     *      {@link IntentFilter} published by a service.
1191     * @param conn Receives information as the service is started and stopped.
1192     * @param flags Operation options for the binding.  May be 0,
1193     *          {@link #BIND_AUTO_CREATE}, {@link #BIND_DEBUG_UNBIND}, or
1194     *          {@link #BIND_NOT_FOREGROUND}.
1195     * @return If you have successfully bound to the service, true is returned;
1196     *         false is returned if the connection is not made so you will not
1197     *         receive the service object.
1198     *
1199     * @throws SecurityException
1200     *
1201     * @see #unbindService
1202     * @see #startService
1203     * @see #BIND_AUTO_CREATE
1204     * @see #BIND_DEBUG_UNBIND
1205     * @see #BIND_NOT_FOREGROUND
1206     */
1207    public abstract boolean bindService(Intent service, ServiceConnection conn,
1208            int flags);
1209
1210    /**
1211     * Disconnect from an application service.  You will no longer receive
1212     * calls as the service is restarted, and the service is now allowed to
1213     * stop at any time.
1214     *
1215     * @param conn The connection interface previously supplied to
1216     *             bindService().
1217     *
1218     * @see #bindService
1219     */
1220    public abstract void unbindService(ServiceConnection conn);
1221
1222    /**
1223     * Start executing an {@link android.app.Instrumentation} class.  The given
1224     * Instrumentation component will be run by killing its target application
1225     * (if currently running), starting the target process, instantiating the
1226     * instrumentation component, and then letting it drive the application.
1227     *
1228     * <p>This function is not synchronous -- it returns as soon as the
1229     * instrumentation has started and while it is running.
1230     *
1231     * <p>Instrumentation is normally only allowed to run against a package
1232     * that is either unsigned or signed with a signature that the
1233     * the instrumentation package is also signed with (ensuring the target
1234     * trusts the instrumentation).
1235     *
1236     * @param className Name of the Instrumentation component to be run.
1237     * @param profileFile Optional path to write profiling data as the
1238     * instrumentation runs, or null for no profiling.
1239     * @param arguments Additional optional arguments to pass to the
1240     * instrumentation, or null.
1241     *
1242     * @return Returns true if the instrumentation was successfully started,
1243     * else false if it could not be found.
1244     */
1245    public abstract boolean startInstrumentation(ComponentName className,
1246            String profileFile, Bundle arguments);
1247
1248    /**
1249     * Return the handle to a system-level service by name. The class of the
1250     * returned object varies by the requested name. Currently available names
1251     * are:
1252     *
1253     * <dl>
1254     *  <dt> {@link #WINDOW_SERVICE} ("window")
1255     *  <dd> The top-level window manager in which you can place custom
1256     *  windows.  The returned object is a {@link android.view.WindowManager}.
1257     *  <dt> {@link #LAYOUT_INFLATER_SERVICE} ("layout_inflater")
1258     *  <dd> A {@link android.view.LayoutInflater} for inflating layout resources
1259     *  in this context.
1260     *  <dt> {@link #ACTIVITY_SERVICE} ("activity")
1261     *  <dd> A {@link android.app.ActivityManager} for interacting with the
1262     *  global activity state of the system.
1263     *  <dt> {@link #POWER_SERVICE} ("power")
1264     *  <dd> A {@link android.os.PowerManager} for controlling power
1265     *  management.
1266     *  <dt> {@link #ALARM_SERVICE} ("alarm")
1267     *  <dd> A {@link android.app.AlarmManager} for receiving intents at the
1268     *  time of your choosing.
1269     *  <dt> {@link #NOTIFICATION_SERVICE} ("notification")
1270     *  <dd> A {@link android.app.NotificationManager} for informing the user
1271     *   of background events.
1272     *  <dt> {@link #KEYGUARD_SERVICE} ("keyguard")
1273     *  <dd> A {@link android.app.KeyguardManager} for controlling keyguard.
1274     *  <dt> {@link #LOCATION_SERVICE} ("location")
1275     *  <dd> A {@link android.location.LocationManager} for controlling location
1276     *   (e.g., GPS) updates.
1277     *  <dt> {@link #SEARCH_SERVICE} ("search")
1278     *  <dd> A {@link android.app.SearchManager} for handling search.
1279     *  <dt> {@link #VIBRATOR_SERVICE} ("vibrator")
1280     *  <dd> A {@link android.os.Vibrator} for interacting with the vibrator
1281     *  hardware.
1282     *  <dt> {@link #CONNECTIVITY_SERVICE} ("connection")
1283     *  <dd> A {@link android.net.ConnectivityManager ConnectivityManager} for
1284     *  handling management of network connections.
1285     *  <dt> {@link #WIFI_SERVICE} ("wifi")
1286     *  <dd> A {@link android.net.wifi.WifiManager WifiManager} for management of
1287     * Wi-Fi connectivity.
1288     * <dt> {@link #INPUT_METHOD_SERVICE} ("input_method")
1289     * <dd> An {@link android.view.inputmethod.InputMethodManager InputMethodManager}
1290     * for management of input methods.
1291     * <dt> {@link #UI_MODE_SERVICE} ("uimode")
1292     * <dd> An {@link android.app.UiModeManager} for controlling UI modes.
1293     * <dt> {@link #DOWNLOAD_SERVICE} ("download")
1294     * <dd> A {@link android.app.DownloadManager} for requesting HTTP downloads
1295     * </dl>
1296     *
1297     * <p>Note:  System services obtained via this API may be closely associated with
1298     * the Context in which they are obtained from.  In general, do not share the
1299     * service objects between various different contexts (Activities, Applications,
1300     * Services, Providers, etc.)
1301     *
1302     * @param name The name of the desired service.
1303     *
1304     * @return The service or null if the name does not exist.
1305     *
1306     * @see #WINDOW_SERVICE
1307     * @see android.view.WindowManager
1308     * @see #LAYOUT_INFLATER_SERVICE
1309     * @see android.view.LayoutInflater
1310     * @see #ACTIVITY_SERVICE
1311     * @see android.app.ActivityManager
1312     * @see #POWER_SERVICE
1313     * @see android.os.PowerManager
1314     * @see #ALARM_SERVICE
1315     * @see android.app.AlarmManager
1316     * @see #NOTIFICATION_SERVICE
1317     * @see android.app.NotificationManager
1318     * @see #KEYGUARD_SERVICE
1319     * @see android.app.KeyguardManager
1320     * @see #LOCATION_SERVICE
1321     * @see android.location.LocationManager
1322     * @see #SEARCH_SERVICE
1323     * @see android.app.SearchManager
1324     * @see #SENSOR_SERVICE
1325     * @see android.hardware.SensorManager
1326     * @see #STORAGE_SERVICE
1327     * @see android.os.storage.StorageManager
1328     * @see #VIBRATOR_SERVICE
1329     * @see android.os.Vibrator
1330     * @see #CONNECTIVITY_SERVICE
1331     * @see android.net.ConnectivityManager
1332     * @see #WIFI_SERVICE
1333     * @see android.net.wifi.WifiManager
1334     * @see #AUDIO_SERVICE
1335     * @see android.media.AudioManager
1336     * @see #TELEPHONY_SERVICE
1337     * @see android.telephony.TelephonyManager
1338     * @see #INPUT_METHOD_SERVICE
1339     * @see android.view.inputmethod.InputMethodManager
1340     * @see #UI_MODE_SERVICE
1341     * @see android.app.UiModeManager
1342     * @see #DOWNLOAD_SERVICE
1343     * @see android.app.DownloadManager
1344     */
1345    public abstract Object getSystemService(String name);
1346
1347    /**
1348     * Use with {@link #getSystemService} to retrieve a
1349     * {@link android.os.PowerManager} for controlling power management,
1350     * including "wake locks," which let you keep the device on while
1351     * you're running long tasks.
1352     */
1353    public static final String POWER_SERVICE = "power";
1354
1355    /**
1356     * Use with {@link #getSystemService} to retrieve a
1357     * {@link android.view.WindowManager} for accessing the system's window
1358     * manager.
1359     *
1360     * @see #getSystemService
1361     * @see android.view.WindowManager
1362     */
1363    public static final String WINDOW_SERVICE = "window";
1364
1365    /**
1366     * Use with {@link #getSystemService} to retrieve a
1367     * {@link android.view.LayoutInflater} for inflating layout resources in this
1368     * context.
1369     *
1370     * @see #getSystemService
1371     * @see android.view.LayoutInflater
1372     */
1373    public static final String LAYOUT_INFLATER_SERVICE = "layout_inflater";
1374
1375    /**
1376     * Use with {@link #getSystemService} to retrieve a
1377     * {@link android.accounts.AccountManager} for receiving intents at a
1378     * time of your choosing.
1379     *
1380     * @see #getSystemService
1381     * @see android.accounts.AccountManager
1382     */
1383    public static final String ACCOUNT_SERVICE = "account";
1384
1385    /**
1386     * Use with {@link #getSystemService} to retrieve a
1387     * {@link android.app.ActivityManager} for interacting with the global
1388     * system state.
1389     *
1390     * @see #getSystemService
1391     * @see android.app.ActivityManager
1392     */
1393    public static final String ACTIVITY_SERVICE = "activity";
1394
1395    /**
1396     * Use with {@link #getSystemService} to retrieve a
1397     * {@link android.app.AlarmManager} for receiving intents at a
1398     * time of your choosing.
1399     *
1400     * @see #getSystemService
1401     * @see android.app.AlarmManager
1402     */
1403    public static final String ALARM_SERVICE = "alarm";
1404
1405    /**
1406     * Use with {@link #getSystemService} to retrieve a
1407     * {@link android.app.NotificationManager} for informing the user of
1408     * background events.
1409     *
1410     * @see #getSystemService
1411     * @see android.app.NotificationManager
1412     */
1413    public static final String NOTIFICATION_SERVICE = "notification";
1414
1415    /**
1416     * Use with {@link #getSystemService} to retrieve a
1417     * {@link android.view.accessibility.AccessibilityManager} for giving the user
1418     * feedback for UI events through the registered event listeners.
1419     *
1420     * @see #getSystemService
1421     * @see android.view.accessibility.AccessibilityManager
1422     */
1423    public static final String ACCESSIBILITY_SERVICE = "accessibility";
1424
1425    /**
1426     * Use with {@link #getSystemService} to retrieve a
1427     * {@link android.app.NotificationManager} for controlling keyguard.
1428     *
1429     * @see #getSystemService
1430     * @see android.app.KeyguardManager
1431     */
1432    public static final String KEYGUARD_SERVICE = "keyguard";
1433
1434    /**
1435     * Use with {@link #getSystemService} to retrieve a {@link
1436     * android.location.LocationManager} for controlling location
1437     * updates.
1438     *
1439     * @see #getSystemService
1440     * @see android.location.LocationManager
1441     */
1442    public static final String LOCATION_SERVICE = "location";
1443
1444    /**
1445     * Use with {@link #getSystemService} to retrieve a
1446     * {@link android.location.CountryDetector} for detecting the country that
1447     * the user is in.
1448     *
1449     * @hide
1450     */
1451    public static final String COUNTRY_DETECTOR = "country_detector";
1452
1453    /**
1454     * Use with {@link #getSystemService} to retrieve a {@link
1455     * android.app.SearchManager} for handling searches.
1456     *
1457     * @see #getSystemService
1458     * @see android.app.SearchManager
1459     */
1460    public static final String SEARCH_SERVICE = "search";
1461
1462    /**
1463     * Use with {@link #getSystemService} to retrieve a {@link
1464     * android.hardware.SensorManager} for accessing sensors.
1465     *
1466     * @see #getSystemService
1467     * @see android.hardware.SensorManager
1468     */
1469    public static final String SENSOR_SERVICE = "sensor";
1470
1471    /**
1472     * Use with {@link #getSystemService} to retrieve a {@link
1473     * android.os.storage.StorageManager} for accessing system storage
1474     * functions.
1475     *
1476     * @see #getSystemService
1477     * @see android.os.storage.StorageManager
1478     */
1479    public static final String STORAGE_SERVICE = "storage";
1480
1481    /**
1482     * Use with {@link #getSystemService} to retrieve a
1483     * com.android.server.WallpaperService for accessing wallpapers.
1484     *
1485     * @see #getSystemService
1486     */
1487    public static final String WALLPAPER_SERVICE = "wallpaper";
1488
1489    /**
1490     * Use with {@link #getSystemService} to retrieve a {@link
1491     * android.os.Vibrator} for interacting with the vibration hardware.
1492     *
1493     * @see #getSystemService
1494     * @see android.os.Vibrator
1495     */
1496    public static final String VIBRATOR_SERVICE = "vibrator";
1497
1498    /**
1499     * Use with {@link #getSystemService} to retrieve a {@link
1500     * android.app.StatusBarManager} for interacting with the status bar.
1501     *
1502     * @see #getSystemService
1503     * @see android.app.StatusBarManager
1504     * @hide
1505     */
1506    public static final String STATUS_BAR_SERVICE = "statusbar";
1507
1508    /**
1509     * Use with {@link #getSystemService} to retrieve a {@link
1510     * android.net.ConnectivityManager} for handling management of
1511     * network connections.
1512     *
1513     * @see #getSystemService
1514     * @see android.net.ConnectivityManager
1515     */
1516    public static final String CONNECTIVITY_SERVICE = "connectivity";
1517
1518    /**
1519     * Use with {@link #getSystemService} to retrieve a {@link
1520     * android.net.ThrottleManager} for handling management of
1521     * throttling.
1522     *
1523     * @hide
1524     * @see #getSystemService
1525     * @see android.net.ThrottleManager
1526     */
1527    public static final String THROTTLE_SERVICE = "throttle";
1528
1529    /**
1530     * Use with {@link #getSystemService} to retrieve a {@link
1531     * android.net.NetworkManagementService} for handling management of
1532     * system network services
1533     *
1534     * @hide
1535     * @see #getSystemService
1536     * @see android.net.NetworkManagementService
1537     */
1538    public static final String NETWORKMANAGEMENT_SERVICE = "network_management";
1539
1540    /**
1541     * Use with {@link #getSystemService} to retrieve a {@link
1542     * android.net.wifi.WifiManager} for handling management of
1543     * Wi-Fi access.
1544     *
1545     * @see #getSystemService
1546     * @see android.net.wifi.WifiManager
1547     */
1548    public static final String WIFI_SERVICE = "wifi";
1549
1550    /**
1551     * Use with {@link #getSystemService} to retrieve a
1552     * {@link android.media.AudioManager} for handling management of volume,
1553     * ringer modes and audio routing.
1554     *
1555     * @see #getSystemService
1556     * @see android.media.AudioManager
1557     */
1558    public static final String AUDIO_SERVICE = "audio";
1559
1560    /**
1561     * Use with {@link #getSystemService} to retrieve a
1562     * {@link android.telephony.TelephonyManager} for handling management the
1563     * telephony features of the device.
1564     *
1565     * @see #getSystemService
1566     * @see android.telephony.TelephonyManager
1567     */
1568    public static final String TELEPHONY_SERVICE = "phone";
1569
1570    /**
1571     * Use with {@link #getSystemService} to retrieve a
1572     * {@link android.text.ClipboardManager} for accessing and modifying
1573     * the contents of the global clipboard.
1574     *
1575     * @see #getSystemService
1576     * @see android.text.ClipboardManager
1577     */
1578    public static final String CLIPBOARD_SERVICE = "clipboard";
1579
1580    /**
1581     * Use with {@link #getSystemService} to retrieve a
1582     * {@link android.view.inputmethod.InputMethodManager} for accessing input
1583     * methods.
1584     *
1585     * @see #getSystemService
1586     */
1587    public static final String INPUT_METHOD_SERVICE = "input_method";
1588
1589    /**
1590     * Use with {@link #getSystemService} to retrieve a
1591     * {@link android.appwidget.AppWidgetManager} for accessing AppWidgets.
1592     *
1593     * @hide
1594     * @see #getSystemService
1595     */
1596    public static final String APPWIDGET_SERVICE = "appwidget";
1597
1598    /**
1599     * Use with {@link #getSystemService} to retrieve an
1600     * {@link android.app.backup.IBackupManager IBackupManager} for communicating
1601     * with the backup mechanism.
1602     * @hide
1603     *
1604     * @see #getSystemService
1605     */
1606    public static final String BACKUP_SERVICE = "backup";
1607
1608    /**
1609     * Use with {@link #getSystemService} to retrieve a
1610     * {@link android.os.DropBoxManager} instance for recording
1611     * diagnostic logs.
1612     * @see #getSystemService
1613     */
1614    public static final String DROPBOX_SERVICE = "dropbox";
1615
1616    /**
1617     * Use with {@link #getSystemService} to retrieve a
1618     * {@link android.app.admin.DevicePolicyManager} for working with global
1619     * device policy management.
1620     *
1621     * @see #getSystemService
1622     */
1623    public static final String DEVICE_POLICY_SERVICE = "device_policy";
1624
1625    /**
1626     * Use with {@link #getSystemService} to retrieve a
1627     * {@link android.app.UiModeManager} for controlling UI modes.
1628     *
1629     * @see #getSystemService
1630     */
1631    public static final String UI_MODE_SERVICE = "uimode";
1632
1633    /**
1634     * Use with {@link #getSystemService} to retrieve a
1635     * {@link android.app.DownloadManager} for requesting HTTP downloads.
1636     *
1637     * @see #getSystemService
1638     */
1639    public static final String DOWNLOAD_SERVICE = "download";
1640
1641    /**
1642     * Use with {@link #getSystemService} to retrieve a
1643     * {@link android.nfc.NfcManager} for using NFC.
1644     *
1645     * @see #getSystemService
1646     */
1647    public static final String NFC_SERVICE = "nfc";
1648
1649    /**
1650     * Use with {@link #getSystemService} to retrieve a
1651     * {@link android.net.sip.SipManager} for accessing the SIP related service.
1652     *
1653     * @see #getSystemService
1654     */
1655    /** @hide */
1656    public static final String SIP_SERVICE = "sip";
1657
1658    /**
1659     * Determine whether the given permission is allowed for a particular
1660     * process and user ID running in the system.
1661     *
1662     * @param permission The name of the permission being checked.
1663     * @param pid The process ID being checked against.  Must be > 0.
1664     * @param uid The user ID being checked against.  A uid of 0 is the root
1665     * user, which will pass every permission check.
1666     *
1667     * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the given
1668     * pid/uid is allowed that permission, or
1669     * {@link PackageManager#PERMISSION_DENIED} if it is not.
1670     *
1671     * @see PackageManager#checkPermission(String, String)
1672     * @see #checkCallingPermission
1673     */
1674    public abstract int checkPermission(String permission, int pid, int uid);
1675
1676    /**
1677     * Determine whether the calling process of an IPC you are handling has been
1678     * granted a particular permission.  This is basically the same as calling
1679     * {@link #checkPermission(String, int, int)} with the pid and uid returned
1680     * by {@link android.os.Binder#getCallingPid} and
1681     * {@link android.os.Binder#getCallingUid}.  One important difference
1682     * is that if you are not currently processing an IPC, this function
1683     * will always fail.  This is done to protect against accidentally
1684     * leaking permissions; you can use {@link #checkCallingOrSelfPermission}
1685     * to avoid this protection.
1686     *
1687     * @param permission The name of the permission being checked.
1688     *
1689     * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the calling
1690     * pid/uid is allowed that permission, or
1691     * {@link PackageManager#PERMISSION_DENIED} if it is not.
1692     *
1693     * @see PackageManager#checkPermission(String, String)
1694     * @see #checkPermission
1695     * @see #checkCallingOrSelfPermission
1696     */
1697    public abstract int checkCallingPermission(String permission);
1698
1699    /**
1700     * Determine whether the calling process of an IPC <em>or you</em> have been
1701     * granted a particular permission.  This is the same as
1702     * {@link #checkCallingPermission}, except it grants your own permissions
1703     * if you are not currently processing an IPC.  Use with care!
1704     *
1705     * @param permission The name of the permission being checked.
1706     *
1707     * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the calling
1708     * pid/uid is allowed that permission, or
1709     * {@link PackageManager#PERMISSION_DENIED} if it is not.
1710     *
1711     * @see PackageManager#checkPermission(String, String)
1712     * @see #checkPermission
1713     * @see #checkCallingPermission
1714     */
1715    public abstract int checkCallingOrSelfPermission(String permission);
1716
1717    /**
1718     * If the given permission is not allowed for a particular process
1719     * and user ID running in the system, throw a {@link SecurityException}.
1720     *
1721     * @param permission The name of the permission being checked.
1722     * @param pid The process ID being checked against.  Must be &gt; 0.
1723     * @param uid The user ID being checked against.  A uid of 0 is the root
1724     * user, which will pass every permission check.
1725     * @param message A message to include in the exception if it is thrown.
1726     *
1727     * @see #checkPermission(String, int, int)
1728     */
1729    public abstract void enforcePermission(
1730            String permission, int pid, int uid, String message);
1731
1732    /**
1733     * If the calling process of an IPC you are handling has not been
1734     * granted a particular permission, throw a {@link
1735     * SecurityException}.  This is basically the same as calling
1736     * {@link #enforcePermission(String, int, int, String)} with the
1737     * pid and uid returned by {@link android.os.Binder#getCallingPid}
1738     * and {@link android.os.Binder#getCallingUid}.  One important
1739     * difference is that if you are not currently processing an IPC,
1740     * this function will always throw the SecurityException.  This is
1741     * done to protect against accidentally leaking permissions; you
1742     * can use {@link #enforceCallingOrSelfPermission} to avoid this
1743     * protection.
1744     *
1745     * @param permission The name of the permission being checked.
1746     * @param message A message to include in the exception if it is thrown.
1747     *
1748     * @see #checkCallingPermission(String)
1749     */
1750    public abstract void enforceCallingPermission(
1751            String permission, String message);
1752
1753    /**
1754     * If neither you nor the calling process of an IPC you are
1755     * handling has been granted a particular permission, throw a
1756     * {@link SecurityException}.  This is the same as {@link
1757     * #enforceCallingPermission}, except it grants your own
1758     * permissions if you are not currently processing an IPC.  Use
1759     * with care!
1760     *
1761     * @param permission The name of the permission being checked.
1762     * @param message A message to include in the exception if it is thrown.
1763     *
1764     * @see #checkCallingOrSelfPermission(String)
1765     */
1766    public abstract void enforceCallingOrSelfPermission(
1767            String permission, String message);
1768
1769    /**
1770     * Grant permission to access a specific Uri to another package, regardless
1771     * of whether that package has general permission to access the Uri's
1772     * content provider.  This can be used to grant specific, temporary
1773     * permissions, typically in response to user interaction (such as the
1774     * user opening an attachment that you would like someone else to
1775     * display).
1776     *
1777     * <p>Normally you should use {@link Intent#FLAG_GRANT_READ_URI_PERMISSION
1778     * Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1779     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION
1780     * Intent.FLAG_GRANT_WRITE_URI_PERMISSION} with the Intent being used to
1781     * start an activity instead of this function directly.  If you use this
1782     * function directly, you should be sure to call
1783     * {@link #revokeUriPermission} when the target should no longer be allowed
1784     * to access it.
1785     *
1786     * <p>To succeed, the content provider owning the Uri must have set the
1787     * {@link android.R.styleable#AndroidManifestProvider_grantUriPermissions
1788     * grantUriPermissions} attribute in its manifest or included the
1789     * {@link android.R.styleable#AndroidManifestGrantUriPermission
1790     * &lt;grant-uri-permissions&gt;} tag.
1791     *
1792     * @param toPackage The package you would like to allow to access the Uri.
1793     * @param uri The Uri you would like to grant access to.
1794     * @param modeFlags The desired access modes.  Any combination of
1795     * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION
1796     * Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1797     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION
1798     * Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
1799     *
1800     * @see #revokeUriPermission
1801     */
1802    public abstract void grantUriPermission(String toPackage, Uri uri,
1803            int modeFlags);
1804
1805    /**
1806     * Remove all permissions to access a particular content provider Uri
1807     * that were previously added with {@link #grantUriPermission}.  The given
1808     * Uri will match all previously granted Uris that are the same or a
1809     * sub-path of the given Uri.  That is, revoking "content://foo/one" will
1810     * revoke both "content://foo/target" and "content://foo/target/sub", but not
1811     * "content://foo".
1812     *
1813     * @param uri The Uri you would like to revoke access to.
1814     * @param modeFlags The desired access modes.  Any combination of
1815     * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION
1816     * Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1817     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION
1818     * Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
1819     *
1820     * @see #grantUriPermission
1821     */
1822    public abstract void revokeUriPermission(Uri uri, int modeFlags);
1823
1824    /**
1825     * Determine whether a particular process and user ID has been granted
1826     * permission to access a specific URI.  This only checks for permissions
1827     * that have been explicitly granted -- if the given process/uid has
1828     * more general access to the URI's content provider then this check will
1829     * always fail.
1830     *
1831     * @param uri The uri that is being checked.
1832     * @param pid The process ID being checked against.  Must be &gt; 0.
1833     * @param uid The user ID being checked against.  A uid of 0 is the root
1834     * user, which will pass every permission check.
1835     * @param modeFlags The type of access to grant.  May be one or both of
1836     * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1837     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
1838     *
1839     * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the given
1840     * pid/uid is allowed to access that uri, or
1841     * {@link PackageManager#PERMISSION_DENIED} if it is not.
1842     *
1843     * @see #checkCallingUriPermission
1844     */
1845    public abstract int checkUriPermission(Uri uri, int pid, int uid, int modeFlags);
1846
1847    /**
1848     * Determine whether the calling process and user ID has been
1849     * granted permission to access a specific URI.  This is basically
1850     * the same as calling {@link #checkUriPermission(Uri, int, int,
1851     * int)} with the pid and uid returned by {@link
1852     * android.os.Binder#getCallingPid} and {@link
1853     * android.os.Binder#getCallingUid}.  One important difference is
1854     * that if you are not currently processing an IPC, this function
1855     * will always fail.
1856     *
1857     * @param uri The uri that is being checked.
1858     * @param modeFlags The type of access to grant.  May be one or both of
1859     * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1860     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
1861     *
1862     * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the caller
1863     * is allowed to access that uri, or
1864     * {@link PackageManager#PERMISSION_DENIED} if it is not.
1865     *
1866     * @see #checkUriPermission(Uri, int, int, int)
1867     */
1868    public abstract int checkCallingUriPermission(Uri uri, int modeFlags);
1869
1870    /**
1871     * Determine whether the calling process of an IPC <em>or you</em> has been granted
1872     * permission to access a specific URI.  This is the same as
1873     * {@link #checkCallingUriPermission}, except it grants your own permissions
1874     * if you are not currently processing an IPC.  Use with care!
1875     *
1876     * @param uri The uri that is being checked.
1877     * @param modeFlags The type of access to grant.  May be one or both of
1878     * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1879     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
1880     *
1881     * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the caller
1882     * is allowed to access that uri, or
1883     * {@link PackageManager#PERMISSION_DENIED} if it is not.
1884     *
1885     * @see #checkCallingUriPermission
1886     */
1887    public abstract int checkCallingOrSelfUriPermission(Uri uri, int modeFlags);
1888
1889    /**
1890     * Check both a Uri and normal permission.  This allows you to perform
1891     * both {@link #checkPermission} and {@link #checkUriPermission} in one
1892     * call.
1893     *
1894     * @param uri The Uri whose permission is to be checked, or null to not
1895     * do this check.
1896     * @param readPermission The permission that provides overall read access,
1897     * or null to not do this check.
1898     * @param writePermission The permission that provides overall write
1899     * acess, or null to not do this check.
1900     * @param pid The process ID being checked against.  Must be &gt; 0.
1901     * @param uid The user ID being checked against.  A uid of 0 is the root
1902     * user, which will pass every permission check.
1903     * @param modeFlags The type of access to grant.  May be one or both of
1904     * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1905     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
1906     *
1907     * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the caller
1908     * is allowed to access that uri or holds one of the given permissions, or
1909     * {@link PackageManager#PERMISSION_DENIED} if it is not.
1910     */
1911    public abstract int checkUriPermission(Uri uri, String readPermission,
1912            String writePermission, int pid, int uid, int modeFlags);
1913
1914    /**
1915     * If a particular process and user ID has not been granted
1916     * permission to access a specific URI, throw {@link
1917     * SecurityException}.  This only checks for permissions that have
1918     * been explicitly granted -- if the given process/uid has more
1919     * general access to the URI's content provider then this check
1920     * will always fail.
1921     *
1922     * @param uri The uri that is being checked.
1923     * @param pid The process ID being checked against.  Must be &gt; 0.
1924     * @param uid The user ID being checked against.  A uid of 0 is the root
1925     * user, which will pass every permission check.
1926     * @param modeFlags The type of access to grant.  May be one or both of
1927     * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1928     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
1929     * @param message A message to include in the exception if it is thrown.
1930     *
1931     * @see #checkUriPermission(Uri, int, int, int)
1932     */
1933    public abstract void enforceUriPermission(
1934            Uri uri, int pid, int uid, int modeFlags, String message);
1935
1936    /**
1937     * If the calling process and user ID has not been granted
1938     * permission to access a specific URI, throw {@link
1939     * SecurityException}.  This is basically the same as calling
1940     * {@link #enforceUriPermission(Uri, int, int, int, String)} with
1941     * the pid and uid returned by {@link
1942     * android.os.Binder#getCallingPid} and {@link
1943     * android.os.Binder#getCallingUid}.  One important difference is
1944     * that if you are not currently processing an IPC, this function
1945     * will always throw a SecurityException.
1946     *
1947     * @param uri The uri that is being checked.
1948     * @param modeFlags The type of access to grant.  May be one or both of
1949     * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1950     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
1951     * @param message A message to include in the exception if it is thrown.
1952     *
1953     * @see #checkCallingUriPermission(Uri, int)
1954     */
1955    public abstract void enforceCallingUriPermission(
1956            Uri uri, int modeFlags, String message);
1957
1958    /**
1959     * If the calling process of an IPC <em>or you</em> has not been
1960     * granted permission to access a specific URI, throw {@link
1961     * SecurityException}.  This is the same as {@link
1962     * #enforceCallingUriPermission}, except it grants your own
1963     * permissions if you are not currently processing an IPC.  Use
1964     * with care!
1965     *
1966     * @param uri The uri that is being checked.
1967     * @param modeFlags The type of access to grant.  May be one or both of
1968     * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1969     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
1970     * @param message A message to include in the exception if it is thrown.
1971     *
1972     * @see #checkCallingOrSelfUriPermission(Uri, int)
1973     */
1974    public abstract void enforceCallingOrSelfUriPermission(
1975            Uri uri, int modeFlags, String message);
1976
1977    /**
1978     * Enforce both a Uri and normal permission.  This allows you to perform
1979     * both {@link #enforcePermission} and {@link #enforceUriPermission} in one
1980     * call.
1981     *
1982     * @param uri The Uri whose permission is to be checked, or null to not
1983     * do this check.
1984     * @param readPermission The permission that provides overall read access,
1985     * or null to not do this check.
1986     * @param writePermission The permission that provides overall write
1987     * acess, or null to not do this check.
1988     * @param pid The process ID being checked against.  Must be &gt; 0.
1989     * @param uid The user ID being checked against.  A uid of 0 is the root
1990     * user, which will pass every permission check.
1991     * @param modeFlags The type of access to grant.  May be one or both of
1992     * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
1993     * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
1994     * @param message A message to include in the exception if it is thrown.
1995     *
1996     * @see #checkUriPermission(Uri, String, String, int, int, int)
1997     */
1998    public abstract void enforceUriPermission(
1999            Uri uri, String readPermission, String writePermission,
2000            int pid, int uid, int modeFlags, String message);
2001
2002    /**
2003     * Flag for use with {@link #createPackageContext}: include the application
2004     * code with the context.  This means loading code into the caller's
2005     * process, so that {@link #getClassLoader()} can be used to instantiate
2006     * the application's classes.  Setting this flags imposes security
2007     * restrictions on what application context you can access; if the
2008     * requested application can not be safely loaded into your process,
2009     * java.lang.SecurityException will be thrown.  If this flag is not set,
2010     * there will be no restrictions on the packages that can be loaded,
2011     * but {@link #getClassLoader} will always return the default system
2012     * class loader.
2013     */
2014    public static final int CONTEXT_INCLUDE_CODE = 0x00000001;
2015
2016    /**
2017     * Flag for use with {@link #createPackageContext}: ignore any security
2018     * restrictions on the Context being requested, allowing it to always
2019     * be loaded.  For use with {@link #CONTEXT_INCLUDE_CODE} to allow code
2020     * to be loaded into a process even when it isn't safe to do so.  Use
2021     * with extreme care!
2022     */
2023    public static final int CONTEXT_IGNORE_SECURITY = 0x00000002;
2024
2025    /**
2026     * Flag for use with {@link #createPackageContext}: a restricted context may
2027     * disable specific features. For instance, a View associated with a restricted
2028     * context would ignore particular XML attributes.
2029     */
2030    public static final int CONTEXT_RESTRICTED = 0x00000004;
2031
2032    /**
2033     * Return a new Context object for the given application name.  This
2034     * Context is the same as what the named application gets when it is
2035     * launched, containing the same resources and class loader.  Each call to
2036     * this method returns a new instance of a Context object; Context objects
2037     * are not shared, however they share common state (Resources, ClassLoader,
2038     * etc) so the Context instance itself is fairly lightweight.
2039     *
2040     * <p>Throws {@link PackageManager.NameNotFoundException} if there is no
2041     * application with the given package name.
2042     *
2043     * <p>Throws {@link java.lang.SecurityException} if the Context requested
2044     * can not be loaded into the caller's process for security reasons (see
2045     * {@link #CONTEXT_INCLUDE_CODE} for more information}.
2046     *
2047     * @param packageName Name of the application's package.
2048     * @param flags Option flags, one of {@link #CONTEXT_INCLUDE_CODE}
2049     *              or {@link #CONTEXT_IGNORE_SECURITY}.
2050     *
2051     * @return A Context for the application.
2052     *
2053     * @throws java.lang.SecurityException
2054     * @throws PackageManager.NameNotFoundException if there is no application with
2055     * the given package name
2056     */
2057    public abstract Context createPackageContext(String packageName,
2058            int flags) throws PackageManager.NameNotFoundException;
2059
2060    /**
2061     * Indicates whether this Context is restricted.
2062     *
2063     * @return True if this Context is restricted, false otherwise.
2064     *
2065     * @see #CONTEXT_RESTRICTED
2066     */
2067    public boolean isRestricted() {
2068        return false;
2069    }
2070}
2071