A Service is an application component representing either an application's desire
to perform a longer-running operation while not interacting with the user
or to supply functionality for other applications to use.

This class was deprecated
in API level 13.
New applications should use Fragments instead of this class;
to continue to run on older devices, you can use the v4 support library
which provides a version of the Fragment API that is compatible down to
DONUT.

A wallpaper service is responsible for showing a live wallpaper behind
applications that would like to sit on top of it.

Class Overview

Interface to global information about an application environment. This is
an abstract class whose implementation is provided by
the Android system. It
allows access to application-specific resources and classes, as well as
up-calls for application-level operations such as launching activities,
broadcasting and receiving intents, etc.

Flag for bindService(Intent, ServiceConnection, int): If binding from an activity, allow the
target service's process importance to be raised based on whether the
activity is visible to the user, regardless whether another flag is
used to reduce the amount that the client process's overall importance
is used to impact it.

This constant was deprecated
in API level 17.
Creating world-readable files is very dangerous, and likely
to cause security holes in applications. It is strongly discouraged;
instead, applications should use more formal mechanism for interactions
such as ContentProvider, BroadcastReceiver, and
Service. There are no guarantees that this
access mode will remain on a file, such as when it goes through a
backup and restore.
File creation mode: allow all other applications to have read access
to the created file.

This constant was deprecated
in API level 17.
Creating world-writable files is very dangerous, and likely
to cause security holes in applications. It is strongly discouraged;
instead, applications should use more formal mechanism for interactions
such as ContentProvider, BroadcastReceiver, and
Service. There are no guarantees that this
access mode will remain on a file, such as when it goes through a
backup and restore.
File creation mode: allow all other applications to have write access
to the created file.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Broadcast the given intent to all interested BroadcastReceivers, delivering
them one at a time to allow more preferred receivers to consume the
broadcast before it is delivered to less preferred receivers.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

See Also

public
static
final
int
BIND_ABOVE_CLIENT

Flag for bindService(Intent, ServiceConnection, int): indicates that the client application
binding to this service considers the service to be more important than
the app itself. When set, the platform will try to have the out of
memory killer kill the app before it kills the service it is bound to, though
this is not guaranteed to be the case.

Constant Value:
8
(0x00000008)

public
static
final
int
BIND_ADJUST_WITH_ACTIVITY

Flag for bindService(Intent, ServiceConnection, int): If binding from an activity, allow the
target service's process importance to be raised based on whether the
activity is visible to the user, regardless whether another flag is
used to reduce the amount that the client process's overall importance
is used to impact it.

Constant Value:
128
(0x00000080)

public
static
final
int
BIND_ALLOW_OOM_MANAGEMENT

Flag for bindService(Intent, ServiceConnection, int): allow the process hosting the bound
service to go through its normal memory management. It will be
treated more like a running service, allowing the system to
(temporarily) expunge the process if low on memory or for some other
whim it may have, and being more aggressive about making it a candidate
to be killed (and restarted) if running for a long time.

Note that prior to ICE_CREAM_SANDWICH,
not supplying this flag would also impact how important the system
consider's the target service's process to be. When set, the only way
for it to be raised was by binding from a service in which case it will
only be important when that activity is in the foreground. Now to
achieve this behavior you must explicitly supply the new flag
BIND_ADJUST_WITH_ACTIVITY. For compatibility, old applications
that don't specify BIND_AUTO_CREATE will automatically have
the flags BIND_WAIVE_PRIORITY and
BIND_ADJUST_WITH_ACTIVITY set for them in order to achieve
the same result.

Constant Value:
1
(0x00000001)

public
static
final
int
BIND_DEBUG_UNBIND

Flag for bindService(Intent, ServiceConnection, int): include debugging help for mismatched
calls to unbind. When this flag is set, the callstack of the following
unbindService(ServiceConnection) call is retained, to be printed if a later
incorrect unbind call is made. Note that doing this requires retaining
information about the binding that was made for the lifetime of the app,
resulting in a leak -- this should only be used for debugging.

Constant Value:
2
(0x00000002)

public
static
final
int
BIND_IMPORTANT

Flag for bindService(Intent, ServiceConnection, int): this service is very important to
the client, so should be brought to the foreground process level
when the client is. Normally a process can only be raised to the
visibility level by a client, even if that client is in the foreground.

Constant Value:
64
(0x00000040)

public
static
final
int
BIND_NOT_FOREGROUND

Flag for bindService(Intent, ServiceConnection, int): don't allow this binding to raise
the target service's process to the foreground scheduling priority.
It will still be raised to at least the same memory priority
as the client (so that its process will not be killable in any
situation where the client is not killable), but for CPU scheduling
purposes it may be left in the background. This only has an impact
in the situation where the binding client is a foreground process
and the target service is in a background process.

Constant Value:
4
(0x00000004)

public
static
final
int
BIND_WAIVE_PRIORITY

Flag for bindService(Intent, ServiceConnection, int): don't impact the scheduling or
memory management priority of the target service's hosting process.
Allows the service's process to be managed on the background LRU list
just like a regular application process in the background.

See Also

public
static
final
int
CONTEXT_IGNORE_SECURITY

Flag for use with createPackageContext(String, int): ignore any security
restrictions on the Context being requested, allowing it to always
be loaded. For use with CONTEXT_INCLUDE_CODE to allow code
to be loaded into a process even when it isn't safe to do so. Use
with extreme care!

Constant Value:
2
(0x00000002)

public
static
final
int
CONTEXT_INCLUDE_CODE

Flag for use with createPackageContext(String, int): include the application
code with the context. This means loading code into the caller's
process, so that getClassLoader() can be used to instantiate
the application's classes. Setting this flags imposes security
restrictions on what application context you can access; if the
requested application can not be safely loaded into your process,
java.lang.SecurityException will be thrown. If this flag is not set,
there will be no restrictions on the packages that can be loaded,
but getClassLoader() will always return the default system
class loader.

Constant Value:
1
(0x00000001)

public
static
final
int
CONTEXT_RESTRICTED

Flag for use with createPackageContext(String, int): a restricted context may
disable specific features. For instance, a View associated with a restricted
context would ignore particular XML attributes.

public
static
final
int
MODE_MULTI_PROCESS

SharedPreference loading flag: when set, the file on disk will
be checked for modification even if the shared preferences
instance is already loaded in this process. This behavior is
sometimes desired in cases where the application has multiple
processes, all writing to the same SharedPreferences file.
Generally there are better forms of communication between
processes, though.

This was the legacy (but undocumented) behavior in and
before Gingerbread (Android 2.3) and this flag is implied when
targetting such releases. For applications targetting SDK
versions greater than Android 2.3, this flag must be
explicitly set if desired.

See Also

public
static
final
int
MODE_WORLD_READABLE

This constant was deprecated
in API level 17.
Creating world-readable files is very dangerous, and likely
to cause security holes in applications. It is strongly discouraged;
instead, applications should use more formal mechanism for interactions
such as ContentProvider, BroadcastReceiver, and
Service. There are no guarantees that this
access mode will remain on a file, such as when it goes through a
backup and restore.
File creation mode: allow all other applications to have read access
to the created file.

See Also

public
static
final
int
MODE_WORLD_WRITEABLE

This constant was deprecated
in API level 17.
Creating world-writable files is very dangerous, and likely
to cause security holes in applications. It is strongly discouraged;
instead, applications should use more formal mechanism for interactions
such as ContentProvider, BroadcastReceiver, and
Service. There are no guarantees that this
access mode will remain on a file, such as when it goes through a
backup and restore.
File creation mode: allow all other applications to have write access
to the created file.

Public Constructors

public
Context()

Public Methods

Connect to an application service, creating it if needed. This defines
a dependency between your application and the service. The given
conn will receive the service object when it is created and be
told if it dies and restarts. The service will be considered required
by the system only for as long as the calling context exists. For
example, if this Context is an Activity that is stopped, the service will
not be required to continue running until the Activity is resumed.

This function will throw SecurityException if you do not
have permission to bind to the given service.

Note: this method can not be called from a
BroadcastReceiver component. A pattern you can use to
communicate from a BroadcastReceiver to a Service is to call
startService(Intent) with the arguments containing the command to be
sent, with the service calling its
stopSelf(int) method when done executing
that command. See the API demo App/Service/Service Start Arguments
Controller for an illustration of this. It is okay, however, to use
this method from a BroadcastReceiver that has been registered with
registerReceiver(BroadcastReceiver, IntentFilter), since the lifetime of this BroadcastReceiver
is tied to another object (the one that registered it).

Parameters

service

Identifies the service to connect to. The Intent may
specify either an explicit component name, or a logical
description (action, category, etc) to match an
IntentFilter published by a service.

conn

Receives information as the service is started and stopped.
This must be a valid ServiceConnection object; it must not be null.

See Also

Determine whether the calling process of an IPC or you have been
granted a particular permission. This is the same as
checkCallingPermission(String), except it grants your own permissions
if you are not currently processing an IPC. Use with care!

See Also

Determine whether the calling process of an IPC or you has been granted
permission to access a specific URI. This is the same as
checkCallingUriPermission(Uri, int), except it grants your own permissions
if you are not currently processing an IPC. Use with care!

See Also

Determine whether the calling process of an IPC you are handling has been
granted a particular permission. This is basically the same as calling
checkPermission(String, int, int) with the pid and uid returned
by getCallingPid() and
getCallingUid(). One important difference
is that if you are not currently processing an IPC, this function
will always fail. This is done to protect against accidentally
leaking permissions; you can use checkCallingOrSelfPermission(String)
to avoid this protection.

See Also

Determine whether the calling process and user ID has been
granted permission to access a specific URI. This is basically
the same as calling checkUriPermission(Uri, int, int, int) with the pid and uid returned by getCallingPid() and getCallingUid(). One important difference is
that if you are not currently processing an IPC, this function
will always fail.

See Also

Determine whether a particular process and user ID has been granted
permission to access a specific URI. This only checks for permissions
that have been explicitly granted -- if the given process/uid has
more general access to the URI's content provider then this check will
always fail.

Parameters

uri

The uri that is being checked.

pid

The process ID being checked against. Must be > 0.

uid

The user ID being checked against. A uid of 0 is the root
user, which will pass every permission check.

Throws

Return a new Context object for the current Context but whose resources
are adjusted to match the given Configuration. Each call to this method
returns a new instance of a Context object; Context objects are not
shared, however common state (ClassLoader, other Resources for the
same configuration) may be so the Context itself can be fairly lightweight.

Parameters

overrideConfiguration

A Configuration specifying what
values to modify in the base Configuration of the original Context's
resources. If the base configuration changes (such as due to an
orientation change), the resources of this context will also change except
for those that have been explicitly overridden with a value here.

Returns

Return a new Context object for the current Context but whose resources
are adjusted to match the metrics of the given Display. Each call to this method
returns a new instance of a Context object; Context objects are not
shared, however common state (ClassLoader, other Resources for the
same configuration) may be so the Context itself can be fairly lightweight.
The returned display Context provides a WindowManager
(see getSystemService(String)) that is configured to show windows
on the given display. The WindowManager's getDefaultDisplay()
method can be used to retrieve the Display from the returned Context.

Parameters

display

A Display object specifying the display
for whose metrics the Context's resources should be tailored and upon which
new windows should be shown.

Returns

Return a new Context object for the given application name. This
Context is the same as what the named application gets when it is
launched, containing the same resources and class loader. Each call to
this method returns a new instance of a Context object; Context objects
are not shared, however they share common state (Resources, ClassLoader,
etc) so the Context instance itself is fairly lightweight.

See Also

If neither you nor the calling process of an IPC you are
handling has been granted a particular permission, throw a
SecurityException. This is the same as enforceCallingPermission(String, String), except it grants your own
permissions if you are not currently processing an IPC. Use
with care!

See Also

If a particular process and user ID has not been granted
permission to access a specific URI, throw SecurityException. This only checks for permissions that have
been explicitly granted -- if the given process/uid has more
general access to the URI's content provider then this check
will always fail.

Parameters

uri

The uri that is being checked.

pid

The process ID being checked against. Must be > 0.

uid

The user ID being checked against. A uid of 0 is the root
user, which will pass every permission check.

Returns

See Also

Return the context of the single, global Application object of the
current process. This generally should only be used if you need a
Context whose lifecycle is separate from the current context, that is
tied to the lifetime of the process rather than the current component.

If used from an Activity context, the receiver is being registered
within that activity. This means that you are expected to unregister
before the activity is done being destroyed; in fact if you do not do
so, the framework will clean up your leaked registration as it removes
the activity and log an error. Thus, if you use the Activity context
to register a receiver that is static (global to the process, not
associated with an Activity instance) then that registration will be
removed on you at whatever point the activity you used is destroyed.

If used from the Context returned here, the receiver is being
registered with the global state associated with your application. Thus
it will never be unregistered for you. This is necessary if the receiver
is associated with static data, not a particular component. However
using the ApplicationContext elsewhere can easily lead to serious leaks
if you forget to unregister, unbind, etc.

Returns the absolute path to the application specific cache directory
on the filesystem. These files will be ones that get deleted first when the
device runs low on storage.
There is no guarantee when these files will be deleted.
Note: you should not rely on the system deleting these
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
files when exceeding that space.

Returns the absolute path to the application specific cache directory on
the filesystem designed for storing cached code. The system will delete
any files stored in this location both when your specific application is
upgraded, and when the entire platform is upgraded.

This location is optimal for storing compiled or optimized code generated
by your application at runtime.

Apps require no extra permissions to read or write to the returned path,
since this path lives in their private storage.

Returns

See Also

Retrieve, creating if needed, a new directory in which the application
can place its own custom data files. You can use the returned File
object to create and access files in this directory. Note that files
created through a File object will only be accessible by your own
application; you can only set the mode of the entire directory, not
of individual files.

Parameters

name

Name of the directory to retrieve. This is a directory
that is created as part of your application data.

Returns

Returns the absolute path to the directory on the primary external filesystem
(that is somewhere on Environment.getExternalStorageDirectory() where the application can
place cache files it owns. These files are internal to the application, and
not typically visible to the user as media.

This is like getCacheDir() in that these
files will be deleted when the application is uninstalled, however there
are some important differences:

The platform does not always monitor the space available in external
storage, and thus may not automatically delete these files. Currently
the only time files here will be deleted by the platform is when running
on JELLY_BEAN_MR1 or later and
Environment.isExternalStorageEmulated() returns true. Note that you should
be managing the maximum space you will use for these anyway, just like
with getCacheDir().

External files are not always available: they will disappear if the
user mounts the external storage on a computer or removes it. See the
APIs on Environment for information in the storage state.

There is no security enforced with these files. For example, any application
holding WRITE_EXTERNAL_STORAGE can write to
these files.

Starting in KITKAT, no permissions
are required to read or write to the returned path; it's always
accessible to the calling app. This only applies to paths generated for
package name of the calling application. To access paths belonging
to other packages, WRITE_EXTERNAL_STORAGE
and/or READ_EXTERNAL_STORAGE are required.

On devices with multiple users (as described by UserManager),
each user has their own isolated external storage. Applications only
have access to the external storage for the user they're running as.

Returns

The path of the directory holding application cache files
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
this method again when it is available.

See Also

Returns absolute paths to application-specific directories on all
external storage devices where the application can place cache files it
owns. These files are internal to the application, and not typically
visible to the user as media.

This is like getCacheDir() in that these files will be deleted when
the application is uninstalled, however there are some important differences:

External files are not always available: they will disappear if the
user mounts the external storage on a computer or removes it.

There is no security enforced with these files.

External storage devices returned here are considered a permanent part of
the device, including both emulated external storage and physical media
slots, such as SD cards in a battery compartment. The returned paths do
not include transient devices, such as USB flash drives.

An application may store data on any or all of the returned devices. For
example, an app may choose to store large files on the device with the
most available space, as measured by StatFs.

No permissions are required to read or write to the returned paths; they
are always accessible to the calling app. Write access outside of these
paths on secondary external storage devices is not available.

The first path returned is the same as getExternalCacheDir().
Returned paths may be null if a storage device is unavailable.

See Also

Returns the absolute path to the directory on the primary external filesystem
(that is somewhere on Environment.getExternalStorageDirectory()) where the application can
place persistent files it owns. These files are internal to the
applications, and not typically visible to the user as media.

This is like getFilesDir() in that these
files will be deleted when the application is uninstalled, however there
are some important differences:

External files are not always available: they will disappear if the
user mounts the external storage on a computer or removes it. See the
APIs on Environment for information in the storage state.

There is no security enforced with these files. For example, any application
holding WRITE_EXTERNAL_STORAGE can write to
these files.

Starting in KITKAT, no permissions
are required to read or write to the returned path; it's always
accessible to the calling app. This only applies to paths generated for
package name of the calling application. To access paths belonging
to other packages, WRITE_EXTERNAL_STORAGE
and/or READ_EXTERNAL_STORAGE are required.

On devices with multiple users (as described by UserManager),
each user has their own isolated external storage. Applications only
have access to the external storage for the user they're running as.

Here is an example of typical code to manipulate a file in
an application's private storage:

void createExternalStoragePrivateFile() {
// Create a path where we will place our private file on external
// storage.
File file = new File(getExternalFilesDir(null), "DemoFile.jpg");
try {
// Very simple code to copy a picture from the application's
// resource into the external file. Note that this code does
// no error checking, and assumes the picture is small (does not
// try to copy it in chunks). Note that if external storage is
// not currently mounted this will silently fail.
InputStream is = getResources().openRawResource(R.drawable.balloons);
OutputStream os = new FileOutputStream(file);
byte[] data = new byte[is.available()];
is.read(data);
os.write(data);
is.close();
os.close();
} catch (IOException e) {
// Unable to create file, likely because external storage is
// not currently mounted.
Log.w("ExternalStorage", "Error writing " + file, e);
}
}
void deleteExternalStoragePrivateFile() {
// Get path for the file on external storage. If external
// storage is not currently mounted this will fail.
File file = new File(getExternalFilesDir(null), "DemoFile.jpg");
if (file != null) {
file.delete();
}
}
boolean hasExternalStoragePrivateFile() {
// Get path for the file on external storage. If external
// storage is not currently mounted this will fail.
File file = new File(getExternalFilesDir(null), "DemoFile.jpg");
if (file != null) {
return file.exists();
}
return false;
}

If you supply a non-null type to this function, the returned
file will be a path to a sub-directory of the given type. Though these files
are not automatically scanned by the media scanner, you can explicitly
add them to the media database with
MediaScannerConnection.scanFile.
Note that this is not the same as
Environment.getExternalStoragePublicDirectory(), which provides
directories of media shared by all applications. The
directories returned here are
owned by the application, and their contents will be removed when the
application is uninstalled. Unlike
Environment.getExternalStoragePublicDirectory(), the directory
returned here will be automatically created for you.

Here is an example of typical code to manipulate a picture in
an application's private storage and add it to the media database:

void createExternalStoragePrivatePicture() {
// Create a path where we will place our picture in our own private
// pictures directory. Note that we don't really need to place a
// picture in DIRECTORY_PICTURES, since the media scanner will see
// all media in these directories; this may be useful with other
// media types such as DIRECTORY_MUSIC however to help it classify
// your media for display to the user.
File path = getExternalFilesDir(Environment.DIRECTORY_PICTURES);
File file = new File(path, "DemoPicture.jpg");
try {
// Very simple code to copy a picture from the application's
// resource into the external file. Note that this code does
// no error checking, and assumes the picture is small (does not
// try to copy it in chunks). Note that if external storage is
// not currently mounted this will silently fail.
InputStream is = getResources().openRawResource(R.drawable.balloons);
OutputStream os = new FileOutputStream(file);
byte[] data = new byte[is.available()];
is.read(data);
os.write(data);
is.close();
os.close();
// Tell the media scanner about the new file so that it is
// immediately available to the user.
MediaScannerConnection.scanFile(this,
new String[] { file.toString() }, null,
new MediaScannerConnection.OnScanCompletedListener() {
public void onScanCompleted(String path, Uri uri) {
Log.i("ExternalStorage", "Scanned " + path + ":");
Log.i("ExternalStorage", "-> uri=" + uri);
}
});
} catch (IOException e) {
// Unable to create file, likely because external storage is
// not currently mounted.
Log.w("ExternalStorage", "Error writing " + file, e);
}
}
void deleteExternalStoragePrivatePicture() {
// Create a path where we will place our picture in the user's
// public pictures directory and delete the file. If external
// storage is not currently mounted this will fail.
File path = getExternalFilesDir(Environment.DIRECTORY_PICTURES);
if (path != null) {
File file = new File(path, "DemoPicture.jpg");
file.delete();
}
}
boolean hasExternalStoragePrivatePicture() {
// Create a path where we will place our picture in the user's
// public pictures directory and check if the file exists. If
// external storage is not currently mounted this will think the
// picture doesn't exist.
File path = getExternalFilesDir(Environment.DIRECTORY_PICTURES);
if (path != null) {
File file = new File(path, "DemoPicture.jpg");
return file.exists();
}
return false;
}

Returns

The path of the directory holding application files
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
this method again when it is available.

See Also

Returns absolute paths to application-specific directories on all
external storage devices where the application can place persistent files
it owns. These files are internal to the application, and not typically
visible to the user as media.

This is like getFilesDir() in that these files will be deleted when
the application is uninstalled, however there are some important differences:

External files are not always available: they will disappear if the
user mounts the external storage on a computer or removes it.

There is no security enforced with these files.

External storage devices returned here are considered a permanent part of
the device, including both emulated external storage and physical media
slots, such as SD cards in a battery compartment. The returned paths do
not include transient devices, such as USB flash drives.

An application may store data on any or all of the returned devices. For
example, an app may choose to store large files on the device with the
most available space, as measured by StatFs.

No permissions are required to read or write to the returned paths; they
are always accessible to the calling app. Write access outside of these
paths on secondary external storage devices is not available.

See Also

Returns absolute paths to application-specific directories on all
external storage devices where the application can place media files.
These files are scanned and made available to other apps through
MediaStore.

This is like getExternalFilesDirs(String) in that these files will be
deleted when the application is uninstalled, however there are some
important differences:

External files are not always available: they will disappear if the
user mounts the external storage on a computer or removes it.

There is no security enforced with these files.

External storage devices returned here are considered a permanent part of
the device, including both emulated external storage and physical media
slots, such as SD cards in a battery compartment. The returned paths do
not include transient devices, such as USB flash drives.

An application may store data on any or all of the returned devices. For
example, an app may choose to store large files on the device with the
most available space, as measured by StatFs.

No permissions are required to read or write to the returned paths; they
are always accessible to the calling app. Write access outside of these
paths on secondary external storage devices is not available.

Returns

Returns the absolute path to the directory on the filesystem similar to
getFilesDir(). The difference is that files placed under this
directory will be excluded from automatic backup to remote storage. See
BackupAgent for a full discussion
of the automatic backup mechanism in Android.

No permissions are required to read or write to the returned path, since this
path is internal storage.

Returns

The path of the directory holding application files that will not be
automatically backed up to remote storage.

See Also

Return the primary external storage directory where this application's OBB
files (if there are any) can be found. Note if the application does not have
any OBB files, this directory may not exist.

This is like getFilesDir() in that these files will be deleted when
the application is uninstalled, however there are some important differences:

External files are not always available: they will disappear if the
user mounts the external storage on a computer or removes it.

There is no security enforced with these files. For example, any application
holding WRITE_EXTERNAL_STORAGE can write to
these files.

Starting in KITKAT, no permissions
are required to read or write to the returned path; it's always
accessible to the calling app. This only applies to paths generated for
package name of the calling application. To access paths belonging
to other packages, WRITE_EXTERNAL_STORAGE
and/or READ_EXTERNAL_STORAGE are required.

On devices with multiple users (as described by UserManager),
multiple users may share the same OBB storage location. Applications
should ensure that multiple instances running under different users don't
interfere with each other.

Returns absolute paths to application-specific directories on all
external storage devices where the application's OBB files (if there are
any) can be found. Note if the application does not have any OBB files,
these directories may not exist.

This is like getFilesDir() in that these files will be deleted when
the application is uninstalled, however there are some important differences:

External files are not always available: they will disappear if the
user mounts the external storage on a computer or removes it.

There is no security enforced with these files.

External storage devices returned here are considered a permanent part of
the device, including both emulated external storage and physical media
slots, such as SD cards in a battery compartment. The returned paths do
not include transient devices, such as USB flash drives.

An application may store data on any or all of the returned devices. For
example, an app may choose to store large files on the device with the
most available space, as measured by StatFs.

No permissions are required to read or write to the returned paths; they
are always accessible to the calling app. Write access outside of these
paths on secondary external storage devices is not available.

The first path returned is the same as getObbDir().
Returned paths may be null if a storage device is unavailable.

Retrieve and hold the contents of the preferences file 'name', returning
a SharedPreferences through which you can retrieve and modify its
values. Only one instance of the SharedPreferences object is returned
to any callers for the same name, meaning they will see each other's
edits as soon as they are made.

Parameters

name

Desired preferences file. If a preferences file by this name
does not exist, it will be created when you retrieve an
editor (SharedPreferences.edit()) and then commit changes (Editor.commit()).

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
service objects between various different contexts (Activities, Applications,
Services, Providers, etc.)

Grant permission to access a specific Uri to another package, regardless
of whether that package has general permission to access the Uri's
content provider. This can be used to grant specific, temporary
permissions, typically in response to user interaction (such as the
user opening an attachment that you would like someone else to
display).

Add a new ComponentCallbacks to the base application of the
Context, which will be called at the same times as the ComponentCallbacks
methods of activities and other components are called. Note that you
must be sure to use unregisterComponentCallbacks(ComponentCallbacks) when
appropriate in the future; this will not be removed for you.

Register a BroadcastReceiver to be run in the main activity thread. The
receiver will be called with any broadcast Intent that
matches filter, in the main application thread.

The system may broadcast Intents that are "sticky" -- these stay
around after the broadcast as finished, to be sent to any later
registrations. If your IntentFilter matches one of these sticky
Intents, that Intent will be returned by this function
and sent to your receiver as if it had just
been broadcast.

There may be multiple sticky Intents that match filter,
in which case each of these will be sent to receiver. In
this case, only one of these can be returned directly by the function;
which of these that is returned is arbitrarily decided by the system.

If you know the Intent your are registering for is sticky, you can
supply null for your receiver. In this case, no receiver is
registered -- the function simply returns the sticky Intent that
matches filter. In the case of multiple matches, the same
rules as described above apply.

As of ICE_CREAM_SANDWICH, receivers
registered with this method will correctly respect the
setPackage(String) specified for an Intent being broadcast.
Prior to that, it would be ignored and delivered to all matching registered
receivers. Be careful if using this for security.

Note: this method cannot be called from a
BroadcastReceiver component; that is, from a BroadcastReceiver
that is declared in an application's manifest. It is okay, however, to call
this method from another BroadcastReceiver that has itself been registered
at run time with registerReceiver(BroadcastReceiver, IntentFilter), since the lifetime of such a
registered BroadcastReceiver is tied to the object that registered it.

Parameters

receiver

The BroadcastReceiver to handle the broadcast.

filter

Selects the Intent broadcasts to be received.

Returns

The first sticky intent found that matches filter,
or null if there are none.

Register to receive intent broadcasts, to run in the context of
scheduler. See
registerReceiver(BroadcastReceiver, IntentFilter) for more
information. This allows you to enforce permissions on who can
broadcast intents to your receiver, or have the receiver run in
a different thread than the main application thread.

As of ICE_CREAM_SANDWICH, receivers
registered with this method will correctly respect the
setPackage(String) specified for an Intent being broadcast.
Prior to that, it would be ignored and delivered to all matching registered
receivers. Be careful if using this for security.

Parameters

receiver

The BroadcastReceiver to handle the broadcast.

filter

Selects the Intent broadcasts to be received.

broadcastPermission

String naming a permissions that a
broadcaster must hold in order to send an Intent to you. If null,
no permission is required.

scheduler

Handler identifying the thread that will receive
the Intent. If null, the main thread of the process will be used.

Returns

The first sticky intent found that matches filter,
or null if there are none.

See Also

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Parameters

See Also

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Version of removeStickyBroadcast(Intent) that allows you to specify the
user the broadcast will be sent to. This is not available to applications
that are not pre-installed on the system image. Using it requires holding
the INTERACT_ACROSS_USERS permission.

See Also

Remove all permissions to access a particular content provider Uri
that were previously added with grantUriPermission(String, Uri, int). The given
Uri will match all previously granted Uris that are the same or a
sub-path of the given Uri. That is, revoking "content://foo/target" will
revoke both "content://foo/target" and "content://foo/target/sub", but not
"content://foo". It will not remove any prefix grants that exist at a
higher level.

Prior to LOLLIPOP, if you did not have
regular permission access to a Uri, but had received access to it through
a specific Uri permission grant, you could not revoke that grant with this
function and a SecurityException would be thrown. As of
LOLLIPOP, this function will not throw a security exception,
but will remove whatever permission grants to the Uri had been given to the app
(or none).

See Also

Broadcast the given intent to all interested BroadcastReceivers, allowing
an optional required permission to be enforced. This
call is asynchronous; it returns immediately, and you will continue
executing while the receivers are run. No results are propagated from
receivers and receivers can not abort the broadcast. If you want
to allow receivers to propagate results or abort the broadcast, you must
send an ordered broadcast using
sendOrderedBroadcast(Intent, String).

Broadcast the given intent to all interested BroadcastReceivers. This
call is asynchronous; it returns immediately, and you will continue
executing while the receivers are run. No results are propagated from
receivers and receivers can not abort the broadcast. If you want
to allow receivers to propagate results or abort the broadcast, you must
send an ordered broadcast using
sendOrderedBroadcast(Intent, String).

Version of sendBroadcast(Intent) that allows you to specify the
user the broadcast will be sent to. This is not available to applications
that are not pre-installed on the system image. Using it requires holding
the INTERACT_ACROSS_USERS permission.

Parameters

intent

The intent to broadcast

user

UserHandle to send the intent to.

See Also

Version of sendBroadcast(Intent, String) that allows you to specify the
user the broadcast will be sent to. This is not available to applications
that are not pre-installed on the system image. Using it requires holding
the INTERACT_ACROSS_USERS permission.

Parameters

intent

The Intent to broadcast; all receivers matching this
Intent will receive the broadcast.

user

UserHandle to send the intent to.

receiverPermission

(optional) String naming a permission that
a receiver must hold in order to receive your broadcast.
If null, no permission is required.

Version of sendBroadcast(Intent) that allows you to
receive data back from the broadcast. This is accomplished by
supplying your own BroadcastReceiver when calling, which will be
treated as a final receiver at the end of the broadcast -- its
onReceive(Context, Intent) method will be called with
the result values collected from the other receivers. The broadcast will
be serialized in the same way as calling
sendOrderedBroadcast(Intent, String).

Like sendBroadcast(Intent), this method is
asynchronous; it will return before
resultReceiver.onReceive() is called.

Broadcast the given intent to all interested BroadcastReceivers, delivering
them one at a time to allow more preferred receivers to consume the
broadcast before it is delivered to less preferred receivers. This
call is asynchronous; it returns immediately, and you will continue
executing while the receivers are run.

See Also

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Version of sendStickyBroadcast(Intent) that allows you to specify the
user the broadcast will be sent to. This is not available to applications
that are not pre-installed on the system image. Using it requires holding
the INTERACT_ACROSS_USERS permission.

Parameters

intent

The Intent to broadcast; all receivers matching this
Intent will receive the broadcast, and the Intent will be held to
be re-broadcast to future receivers.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Version of sendStickyBroadcast(Intent) that allows you to
receive data back from the broadcast. This is accomplished by
supplying your own BroadcastReceiver when calling, which will be
treated as a final receiver at the end of the broadcast -- its
onReceive(Context, Intent) method will be called with
the result values collected from the other receivers. The broadcast will
be serialized in the same way as calling
sendOrderedBroadcast(Intent, String).

Like sendBroadcast(Intent), this method is
asynchronous; it will return before
resultReceiver.onReceive() is called. Note that the sticky data
stored is only the data you initially supply to the broadcast, not
the result of any changes made by the receivers.

This method was deprecated
in API level 21.
Sticky broadcasts should not be used. They provide no security (anyone
can access them), no protection (anyone can modify them), and many other problems.
The recommended pattern is to use a non-sticky broadcast to report that something
has changed, with another mechanism for apps to retrieve the current value whenever
desired.

Throws

Launch multiple new activities. This is generally the same as calling
startActivity(Intent) for the first Intent in the array,
that activity during its creation calling startActivity(Intent)
for the second entry, etc. Note that unlike that approach, generally
none of the activities except the last in the array will be created
at this point, but rather will be created when the user first visits
them (due to pressing back from the activity on top).

This method throws ActivityNotFoundException
if there was no Activity found for any given Intent. In this
case the state of the activity stack is undefined (some Intents in the
list may be on it, some not), so you probably want to avoid such situations.

Throws

See Also

Launch a new activity. You will not receive any information about when
the activity exits.

Note that if this method is being called from outside of an
Activity Context, then the Intent must include
the FLAG_ACTIVITY_NEW_TASK launch flag. This is because,
without being started from an existing Activity, there is no existing
task in which to place the new activity and thus it needs to be placed
in its own separate task.

Parameters

intent

The description of the activity to start.

options

Additional options for how the Activity should be started.
May be null if there are no options. See ActivityOptions
for how to build the Bundle supplied here; there are no supported definitions
for building it manually.

See Also

Start executing an Instrumentation class. The given
Instrumentation component will be run by killing its target application
(if currently running), starting the target process, instantiating the
instrumentation component, and then letting it drive the application.

This function is not synchronous -- it returns as soon as the
instrumentation has started and while it is running.

Instrumentation is normally only allowed to run against a package
that is either unsigned or signed with a signature that the
the instrumentation package is also signed with (ensuring the target
trusts the instrumentation).

Parameters

className

Name of the Instrumentation component to be run.

profileFile

Optional path to write profiling data as the
instrumentation runs, or null for no profiling.

arguments

Additional optional arguments to pass to the
instrumentation, or null.

Returns

true if the instrumentation was successfully started,
else false if it could not be found.

Parameters

Intent flags in the original IntentSender that you
would like to change.

flagsValues

Desired values for any bits set in
flagsMask

extraFlags

Always set to 0.

options

Additional options for how the Activity should be started.
See Context.startActivity(Intent, Bundle) for more details. If options
have also been supplied by the IntentSender, options given here will
override any that conflict with those given by the IntentSender.

Throws

See Also

Request that a given application service be started. The Intent
should contain either contain the complete class name of a specific service
implementation to start or a specific package name to target. If the
Intent is less specified, it log a warning about this and which of the
multiple matching services it finds and uses will be undefined. If this service
is not already running, it will be instantiated and started (creating a
process for it if needed); if it is running then it remains running.

Every call to this method will result in a corresponding call to
the target service's onStartCommand(Intent, int, int) method,
with the intent given here. This provides a convenient way
to submit jobs to a service without having to bind and call on to its
interface.

Using startService() overrides the default service lifetime that is
managed by bindService(Intent, ServiceConnection, int): it requires the service to remain
running until stopService(Intent) is called, regardless of whether
any clients are connected to it. Note that calls to startService()
are not nesting: no matter how many times you call startService(),
a single call to stopService(Intent) will stop it.

The system attempts to keep running services around as much as
possible. The only time they should be stopped is if the current
foreground application is using so many resources that the service needs
to be killed. If any errors happen in the service's process, it will
automatically be restarted.

This function will throw SecurityException if you do not
have permission to start the given service.

Parameters

service

Identifies the service to be started. The Intent must be either
fully explicit (supplying a component name) or specify a specific package
name it is targetted to. Additional values
may be included in the Intent extras to supply arguments along with
this specific start call.

Returns

If the service is being started or is already running, the
ComponentName of the actual service that was started is
returned; else if the service does not exist null is returned.

Throws

See Also

Request that a given application service be stopped. If the service is
not running, nothing happens. Otherwise it is stopped. Note that calls
to startService() are not counted -- this stops the service no matter
how many times it was started.

Note that if a stopped service still has ServiceConnection
objects bound to it with the BIND_AUTO_CREATE set, it will
not be destroyed until all of these bindings are removed. See
the Service documentation for more details on a
service's lifecycle.

This function will throw SecurityException if you do not
have permission to stop the given service.

Parameters

service

Description of the service to be stopped. The Intent must be either
fully explicit (supplying a component name) or specify a specific package
name it is targetted to.

Returns

If there is a service matching the given Intent that is already
running, then it is stopped and true is returned; else false is returned.