Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "docs: fix a couple api links" into gingerbread

Browse Source
This commit is contained in:
Scott Main
2010-10-25 11:18:28 -07:00
committed by Android (Google) Code Review
parent 79e76f52a6 4b5da6829a
commit abb50f1528
1 changed files with 59 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
core/java/android/content/Context.java
View File

@@ -80,7 +80,8 @@ public abstract class Context {
/** /**
* Flag for {@link #bindService}: automatically create the service as long * Flag for {@link #bindService}: automatically create the service as long
* as the binding exists. Note that while this will create the service, * as the binding exists. Note that while this will create the service,
* its {@link android.app.Service#onStart} method will still only be called due to an * its {@link android.app.Service#onStartCommand}
* method will still only be called due to an
* explicit call to {@link #startService}. Even without that, though, * explicit call to {@link #startService}. Even without that, though,
* this still provides you with access to the service object while the * this still provides you with access to the service object while the
* service is created. * service is created.
@@ -134,13 +135,13 @@ public abstract class Context {
* services, etc). * services, etc).
*/ */
public abstract Looper getMainLooper(); public abstract Looper getMainLooper();
/** /**
* Return the context of the single, global Application object of the * Return the context of the single, global Application object of the
* current process. This generally should only be used if you need a * current process. This generally should only be used if you need a
* Context whose lifecycle is separate from the current context, that is * Context whose lifecycle is separate from the current context, that is
* tied to the lifetime of the process rather than the current component. * tied to the lifetime of the process rather than the current component.
* *
* <p>Consider for example how this interacts with * <p>Consider for example how this interacts with
* {@ #registerReceiver(BroadcastReceiver, IntentFilter)}: * {@ #registerReceiver(BroadcastReceiver, IntentFilter)}:
* <ul> * <ul>
@@ -269,7 +270,7 @@ public abstract class Context {
/** Return the full application info for this context's package. */ /** Return the full application info for this context's package. */
public abstract ApplicationInfo getApplicationInfo(); public abstract ApplicationInfo getApplicationInfo();
/** /**
* Return the full path to this context's primary Android package. * Return the full path to this context's primary Android package.
* The Android package is a ZIP file which contains the application's * The Android package is a ZIP file which contains the application's
@@ -412,18 +413,18 @@ public abstract class Context {
* @see #getDir * @see #getDir
*/ */
public abstract File getFilesDir(); public abstract File getFilesDir();
/** /**
* Returns the absolute path to the directory on the external filesystem * Returns the absolute path to the directory on the external filesystem
* (that is somewhere on {@link android.os.Environment#getExternalStorageDirectory() * (that is somewhere on {@link android.os.Environment#getExternalStorageDirectory()
* Environment.getExternalStorageDirectory()}) where the application can * Environment.getExternalStorageDirectory()}) where the application can
* place persistent files it owns. These files are private to the * place persistent files it owns. These files are private to the
* applications, and not typically visible to the user as media. * applications, and not typically visible to the user as media.
* *
* <p>This is like {@link #getFilesDir()} in that these * <p>This is like {@link #getFilesDir()} in that these
* files will be deleted when the application is uninstalled, however there * files will be deleted when the application is uninstalled, however there
* are some important differences: * are some important differences:
* *
* <ul> * <ul>
* <li>External files are not always available: they will disappear if the * <li>External files are not always available: they will disappear if the
* user mounts the external storage on a computer or removes it. See the * user mounts the external storage on a computer or removes it. See the
@@ -431,10 +432,10 @@ public abstract class Context {
* <li>There is no security enforced with these files. All applications * <li>There is no security enforced with these files. All applications
* can read and write files placed here. * can read and write files placed here.
* </ul> * </ul>
* *
* <p>Here is an example of typical code to manipulate a file in * <p>Here is an example of typical code to manipulate a file in
* an application's private storage:</p> * an application's private storage:</p>
* *
* {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
* private_file} * private_file}
* *
@@ -454,13 +455,13 @@ public abstract class Context {
* {@link android.os.Environment#getExternalStoragePublicDirectory * {@link android.os.Environment#getExternalStoragePublicDirectory
* Environment.getExternalStoragePublicDirectory()}, the directory * Environment.getExternalStoragePublicDirectory()}, the directory
* returned here will be automatically created for you. * returned here will be automatically created for you.
* *
* <p>Here is an example of typical code to manipulate a picture in * <p>Here is an example of typical code to manipulate a picture in
* an application's private storage and add it to the media database:</p> * an application's private storage and add it to the media database:</p>
* *
* {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
* private_picture} * private_picture}
* *
* @param type The type of files directory to return. May be null for * @param type The type of files directory to return. May be null for
* the root of the files directory or one of * the root of the files directory or one of
* the following Environment constants for a subdirectory: * the following Environment constants for a subdirectory:
@@ -471,7 +472,7 @@ public abstract class Context {
* {@link android.os.Environment#DIRECTORY_NOTIFICATIONS}, * {@link android.os.Environment#DIRECTORY_NOTIFICATIONS},
* {@link android.os.Environment#DIRECTORY_PICTURES}, or * {@link android.os.Environment#DIRECTORY_PICTURES}, or
* {@link android.os.Environment#DIRECTORY_MOVIES}. * {@link android.os.Environment#DIRECTORY_MOVIES}.
* *
* @return Returns the path of the directory holding application files * @return Returns the path of the directory holding application files
* on external storage. Returns null if external storage is not currently * on external storage. Returns null if external storage is not currently
* mounted so it could not ensure the path exists; you will need to call * mounted so it could not ensure the path exists; you will need to call
@@ -481,18 +482,18 @@ public abstract class Context {
* @see android.os.Environment#getExternalStoragePublicDirectory * @see android.os.Environment#getExternalStoragePublicDirectory
*/ */
public abstract File getExternalFilesDir(String type); public abstract File getExternalFilesDir(String type);
/** /**
* Returns the absolute path to the application specific cache directory * Returns the absolute path to the application specific cache directory
* on the filesystem. These files will be ones that get deleted first when the * on the filesystem. These files will be ones that get deleted first when the
* device runs low on storage. * device runs low on storage.
* There is no guarantee when these files will be deleted. * There is no guarantee when these files will be deleted.
* *
* <strong>Note: you should not <em>rely</em> on the system deleting these * <strong>Note: you should not <em>rely</em> on the system deleting these
* files for you; you should always have a reasonable maximum, such as 1 MB, * files for you; you should always have a reasonable maximum, such as 1 MB,
* for the amount of space you consume with cache files, and prune those * for the amount of space you consume with cache files, and prune those
* files when exceeding that space.</strong> * files when exceeding that space.</strong>
* *
* @return Returns the path of the directory holding application cache files. * @return Returns the path of the directory holding application cache files.
* *
* @see #openFileOutput * @see #openFileOutput
@@ -506,11 +507,11 @@ public abstract class Context {
* (that is somewhere on {@link android.os.Environment#getExternalStorageDirectory() * (that is somewhere on {@link android.os.Environment#getExternalStorageDirectory()
* Environment.getExternalStorageDirectory()} where the application can * Environment.getExternalStorageDirectory()} where the application can
* place cache files it owns. * place cache files it owns.
* *
* <p>This is like {@link #getCacheDir()} in that these * <p>This is like {@link #getCacheDir()} in that these
* files will be deleted when the application is uninstalled, however there * files will be deleted when the application is uninstalled, however there
* are some important differences: * are some important differences:
* *
* <ul> * <ul>
* <li>The platform does not monitor the space available in external storage, * <li>The platform does not monitor the space available in external storage,
* and thus will not automatically delete these files. Note that you should * and thus will not automatically delete these files. Note that you should
@@ -531,7 +532,7 @@ public abstract class Context {
* @see #getCacheDir * @see #getCacheDir
*/ */
public abstract File getExternalCacheDir(); public abstract File getExternalCacheDir();
/** /**
* Returns an array of strings naming the private files associated with * Returns an array of strings naming the private files associated with
* this Context's application package. * this Context's application package.
@@ -702,7 +703,7 @@ public abstract class Context {
* here; otherwise, its associated action will be executed (such as * here; otherwise, its associated action will be executed (such as
* sending a broadcast) as if you had called * sending a broadcast) as if you had called
* {@link IntentSender#sendIntent IntentSender.sendIntent} on it. * {@link IntentSender#sendIntent IntentSender.sendIntent} on it.
* *
* @param intent The IntentSender to launch. * @param intent The IntentSender to launch.
* @param fillInIntent If non-null, this will be provided as the * @param fillInIntent If non-null, this will be provided as the
* intent parameter to {@link IntentSender#sendIntent}. * intent parameter to {@link IntentSender#sendIntent}.
@@ -855,7 +856,7 @@ public abstract class Context {
* @see #sendStickyOrderedBroadcast(Intent, BroadcastReceiver, Handler, int, String, Bundle) * @see #sendStickyOrderedBroadcast(Intent, BroadcastReceiver, Handler, int, String, Bundle)
*/ */
public abstract void sendStickyBroadcast(Intent intent); public abstract void sendStickyBroadcast(Intent intent);
/** /**
* Version of {@link #sendStickyBroadcast} that allows you to * Version of {@link #sendStickyBroadcast} that allows you to
* receive data back from the broadcast. This is accomplished by * receive data back from the broadcast. This is accomplished by
@@ -1011,7 +1012,7 @@ public abstract class Context {
* process for it if needed); if it is running then it remains running. * process for it if needed); if it is running then it remains running.
* *
* <p>Every call to this method will result in a corresponding call to * <p>Every call to this method will result in a corresponding call to
* the target service's {@link android.app.Service#onStart} method, * the target service's {@link android.app.Service#onStartCommand} method,
* with the <var>intent</var> given here. This provides a convenient way * with the <var>intent</var> given here. This provides a convenient way
* to submit jobs to a service without having to bind and call on to its * to submit jobs to a service without having to bind and call on to its
* interface. * interface.
@@ -1108,8 +1109,9 @@ public abstract class Context {
* description (action, category, etc) to match an * description (action, category, etc) to match an
* {@link IntentFilter} published by a service. * {@link IntentFilter} published by a service.
* @param conn Receives information as the service is started and stopped. * @param conn Receives information as the service is started and stopped.
* @param flags Operation options for the binding. May be 0 or * @param flags Operation options for the binding. May be 0,
* {@link #BIND_AUTO_CREATE}. * {@link #BIND_AUTO_CREATE}, {@link #BIND_DEBUG_UNBIND}, or
* {@link #BIND_NOT_FOREGROUND}.
* @return If you have successfully bound to the service, true is returned; * @return If you have successfully bound to the service, true is returned;
* false is returned if the connection is not made so you will not * false is returned if the connection is not made so you will not
* receive the service object. * receive the service object.
@@ -1119,6 +1121,8 @@ public abstract class Context {
* @see #unbindService * @see #unbindService
* @see #startService * @see #startService
* @see #BIND_AUTO_CREATE * @see #BIND_AUTO_CREATE
* @see #BIND_DEBUG_UNBIND
* @see #BIND_NOT_FOREGROUND
*/ */
public abstract boolean bindService(Intent service, ServiceConnection conn, public abstract boolean bindService(Intent service, ServiceConnection conn,
int flags); int flags);
@@ -1165,7 +1169,7 @@ public abstract class Context {
* Return the handle to a system-level service by name. The class of the * Return the handle to a system-level service by name. The class of the
* returned object varies by the requested name. Currently available names * returned object varies by the requested name. Currently available names
* are: * are:
* *
* <dl> * <dl>
* <dt> {@link #WINDOW_SERVICE} ("window") * <dt> {@link #WINDOW_SERVICE} ("window")
* <dd> The top-level window manager in which you can place custom * <dd> The top-level window manager in which you can place custom
@@ -1209,16 +1213,16 @@ public abstract class Context {
* <dt> {@link #DOWNLOAD_SERVICE} ("download") * <dt> {@link #DOWNLOAD_SERVICE} ("download")
* <dd> A {@link android.app.DownloadManager} for requesting HTTP downloads * <dd> A {@link android.app.DownloadManager} for requesting HTTP downloads
* </dl> * </dl>
* *
* <p>Note: System services obtained via this API may be closely associated with * <p>Note: System services obtained via this API may be closely associated with
* the Context in which they are obtained from. In general, do not share the * the Context in which they are obtained from. In general, do not share the
* service objects between various different contexts (Activities, Applications, * service objects between various different contexts (Activities, Applications,
* Services, Providers, etc.) * Services, Providers, etc.)
* *
* @param name The name of the desired service. * @param name The name of the desired service.
* *
* @return The service or null if the name does not exist. * @return The service or null if the name does not exist.
* *
* @see #WINDOW_SERVICE * @see #WINDOW_SERVICE
* @see android.view.WindowManager * @see android.view.WindowManager
* @see #LAYOUT_INFLATER_SERVICE * @see #LAYOUT_INFLATER_SERVICE
@@ -1267,7 +1271,7 @@ public abstract class Context {
* you're running long tasks. * you're running long tasks.
*/ */
public static final String POWER_SERVICE = "power"; public static final String POWER_SERVICE = "power";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.view.WindowManager} for accessing the system's window * {@link android.view.WindowManager} for accessing the system's window
@@ -1277,7 +1281,7 @@ public abstract class Context {
* @see android.view.WindowManager * @see android.view.WindowManager
*/ */
public static final String WINDOW_SERVICE = "window"; public static final String WINDOW_SERVICE = "window";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.view.LayoutInflater} for inflating layout resources in this * {@link android.view.LayoutInflater} for inflating layout resources in this
@@ -1287,7 +1291,7 @@ public abstract class Context {
* @see android.view.LayoutInflater * @see android.view.LayoutInflater
*/ */
public static final String LAYOUT_INFLATER_SERVICE = "layout_inflater"; public static final String LAYOUT_INFLATER_SERVICE = "layout_inflater";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.accounts.AccountManager} for receiving intents at a * {@link android.accounts.AccountManager} for receiving intents at a
@@ -1297,7 +1301,7 @@ public abstract class Context {
* @see android.accounts.AccountManager * @see android.accounts.AccountManager
*/ */
public static final String ACCOUNT_SERVICE = "account"; public static final String ACCOUNT_SERVICE = "account";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.app.ActivityManager} for interacting with the global * {@link android.app.ActivityManager} for interacting with the global
@@ -1307,7 +1311,7 @@ public abstract class Context {
* @see android.app.ActivityManager * @see android.app.ActivityManager
*/ */
public static final String ACTIVITY_SERVICE = "activity"; public static final String ACTIVITY_SERVICE = "activity";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.app.AlarmManager} for receiving intents at a * {@link android.app.AlarmManager} for receiving intents at a
@@ -1317,7 +1321,7 @@ public abstract class Context {
* @see android.app.AlarmManager * @see android.app.AlarmManager
*/ */
public static final String ALARM_SERVICE = "alarm"; public static final String ALARM_SERVICE = "alarm";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.app.NotificationManager} for informing the user of * {@link android.app.NotificationManager} for informing the user of
@@ -1327,7 +1331,7 @@ public abstract class Context {
* @see android.app.NotificationManager * @see android.app.NotificationManager
*/ */
public static final String NOTIFICATION_SERVICE = "notification"; public static final String NOTIFICATION_SERVICE = "notification";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.view.accessibility.AccessibilityManager} for giving the user * {@link android.view.accessibility.AccessibilityManager} for giving the user
@@ -1337,7 +1341,7 @@ public abstract class Context {
* @see android.view.accessibility.AccessibilityManager * @see android.view.accessibility.AccessibilityManager
*/ */
public static final String ACCESSIBILITY_SERVICE = "accessibility"; public static final String ACCESSIBILITY_SERVICE = "accessibility";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.app.NotificationManager} for controlling keyguard. * {@link android.app.NotificationManager} for controlling keyguard.
@@ -1346,7 +1350,7 @@ public abstract class Context {
* @see android.app.KeyguardManager * @see android.app.KeyguardManager
*/ */
public static final String KEYGUARD_SERVICE = "keyguard"; public static final String KEYGUARD_SERVICE = "keyguard";
/** /**
* Use with {@link #getSystemService} to retrieve a {@link * Use with {@link #getSystemService} to retrieve a {@link
* android.location.LocationManager} for controlling location * android.location.LocationManager} for controlling location
@@ -1356,7 +1360,7 @@ public abstract class Context {
* @see android.location.LocationManager * @see android.location.LocationManager
*/ */
public static final String LOCATION_SERVICE = "location"; public static final String LOCATION_SERVICE = "location";
/** /**
* Use with {@link #getSystemService} to retrieve a {@link * Use with {@link #getSystemService} to retrieve a {@link
* android.app.SearchManager} for handling searches. * android.app.SearchManager} for handling searches.
@@ -1365,7 +1369,7 @@ public abstract class Context {
* @see android.app.SearchManager * @see android.app.SearchManager
*/ */
public static final String SEARCH_SERVICE = "search"; public static final String SEARCH_SERVICE = "search";
/** /**
* Use with {@link #getSystemService} to retrieve a {@link * Use with {@link #getSystemService} to retrieve a {@link
* android.hardware.SensorManager} for accessing sensors. * android.hardware.SensorManager} for accessing sensors.
@@ -1374,7 +1378,7 @@ public abstract class Context {
* @see android.hardware.SensorManager * @see android.hardware.SensorManager
*/ */
public static final String SENSOR_SERVICE = "sensor"; public static final String SENSOR_SERVICE = "sensor";
/** /**
* Use with {@link #getSystemService} to retrieve a {@link * Use with {@link #getSystemService} to retrieve a {@link
* android.os.storage.StorageManager} for accessing system storage * android.os.storage.StorageManager} for accessing system storage
@@ -1392,7 +1396,7 @@ public abstract class Context {
* @see #getSystemService * @see #getSystemService
*/ */
public static final String WALLPAPER_SERVICE = "wallpaper"; public static final String WALLPAPER_SERVICE = "wallpaper";
/** /**
* Use with {@link #getSystemService} to retrieve a {@link * Use with {@link #getSystemService} to retrieve a {@link
* android.os.Vibrator} for interacting with the vibration hardware. * android.os.Vibrator} for interacting with the vibration hardware.
@@ -1453,22 +1457,22 @@ public abstract class Context {
* @see android.net.wifi.WifiManager * @see android.net.wifi.WifiManager
*/ */
public static final String WIFI_SERVICE = "wifi"; public static final String WIFI_SERVICE = "wifi";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.media.AudioManager} for handling management of volume, * {@link android.media.AudioManager} for handling management of volume,
* ringer modes and audio routing. * ringer modes and audio routing.
* *
* @see #getSystemService * @see #getSystemService
* @see android.media.AudioManager * @see android.media.AudioManager
*/ */
public static final String AUDIO_SERVICE = "audio"; public static final String AUDIO_SERVICE = "audio";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.telephony.TelephonyManager} for handling management the * {@link android.telephony.TelephonyManager} for handling management the
* telephony features of the device. * telephony features of the device.
* *
* @see #getSystemService * @see #getSystemService
* @see android.telephony.TelephonyManager * @see android.telephony.TelephonyManager
*/ */
@@ -1478,14 +1482,14 @@ public abstract class Context {
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.text.ClipboardManager} for accessing and modifying * {@link android.text.ClipboardManager} for accessing and modifying
* the contents of the global clipboard. * the contents of the global clipboard.
* *
* @see #getSystemService * @see #getSystemService
* @see android.text.ClipboardManager * @see android.text.ClipboardManager
*/ */
public static final String CLIPBOARD_SERVICE = "clipboard"; public static final String CLIPBOARD_SERVICE = "clipboard";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.view.inputmethod.InputMethodManager} for accessing input * {@link android.view.inputmethod.InputMethodManager} for accessing input
* methods. * methods.
* *
@@ -1507,7 +1511,7 @@ public abstract class Context {
* {@link android.app.backup.IBackupManager IBackupManager} for communicating * {@link android.app.backup.IBackupManager IBackupManager} for communicating
* with the backup mechanism. * with the backup mechanism.
* @hide * @hide
* *
* @see #getSystemService * @see #getSystemService
*/ */
public static final String BACKUP_SERVICE = "backup"; public static final String BACKUP_SERVICE = "backup";
@@ -1521,7 +1525,7 @@ public abstract class Context {
public static final String DROPBOX_SERVICE = "dropbox"; public static final String DROPBOX_SERVICE = "dropbox";
/** /**
* Use with {@link #getSystemService} to retrieve a * Use with {@link #getSystemService} to retrieve a
* {@link android.app.admin.DevicePolicyManager} for working with global * {@link android.app.admin.DevicePolicyManager} for working with global
* device policy management. * device policy management.
* *
@@ -1861,7 +1865,7 @@ public abstract class Context {
* #enforceCallingUriPermission}, except it grants your own * #enforceCallingUriPermission}, except it grants your own
* permissions if you are not currently processing an IPC. Use * permissions if you are not currently processing an IPC. Use
* with care! * with care!
* *
* @param uri The uri that is being checked. * @param uri The uri that is being checked.
* @param modeFlags The type of access to grant. May be one or both of * @param modeFlags The type of access to grant. May be one or both of
* {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
@@ -1877,7 +1881,7 @@ public abstract class Context {
* Enforce both a Uri and normal permission. This allows you to perform * Enforce both a Uri and normal permission. This allows you to perform
* both {@link #enforcePermission} and {@link #enforceUriPermission} in one * both {@link #enforcePermission} and {@link #enforceUriPermission} in one
* call. * call.
* *
* @param uri The Uri whose permission is to be checked, or null to not * @param uri The Uri whose permission is to be checked, or null to not
* do this check. * do this check.
* @param readPermission The permission that provides overall read access, * @param readPermission The permission that provides overall read access,
@@ -1920,7 +1924,7 @@ public abstract class Context {
* with extreme care! * with extreme care!
*/ */
public static final int CONTEXT_IGNORE_SECURITY = 0x00000002; public static final int CONTEXT_IGNORE_SECURITY = 0x00000002;
/** /**
* Flag for use with {@link #createPackageContext}: a restricted context may * Flag for use with {@link #createPackageContext}: a restricted context may
* disable specific features. For instance, a View associated with a restricted * disable specific features. For instance, a View associated with a restricted
@@ -1958,9 +1962,9 @@ public abstract class Context {
/** /**
* Indicates whether this Context is restricted. * Indicates whether this Context is restricted.
* *
* @return True if this Context is restricted, false otherwise. * @return True if this Context is restricted, false otherwise.
* *
* @see #CONTEXT_RESTRICTED * @see #CONTEXT_RESTRICTED
*/ */
public boolean isRestricted() { public boolean isRestricted() {